Request and Response Examples

This document shows complete calls against the API: the request as sent and the response as returned, for the flows an integrator builds first. Identifiers, names, and amounts in the examples are illustrative; shapes, field names, and status codes are as specified in the endpoint references. Every call is against the base URL https://www.aapawz.com/api and carries the header Authorization: Bearer <your-api-key> (Authentication Endpoints).

1. Verify your key

GET /account
Authorization: Bearer <your-api-key>

{
  "id": "acct_7k2m9x",
  "name": "Acme Pet Supply Co.",
  "account_type": "supplier",
  "api_tier": "import",
  "status": "active"
}

A 401 here means the key itself is wrong; fix that before debugging anything else (Error Codes).

2. Create a product

POST /catalog/products
Authorization: Bearer <your-api-key>
Idempotency-Key: import-2026-10-14-acme-dogfood
Content-Type: application/json

{
  "seller_sku": "ACME-DOGFOOD-10LB",
  "title": "Acme Grain-Free Dog Food, 10 lb",
  "description": "A complete dry food for adult dogs.",
  "brand": "Acme",
  "category_id": "cat_pet_food",
  "barcode": "012345678905",
  "attributes": { "life_stage": "adult", "weight": "10 lb" }
}

Response 201

{
  "id": "prod_8f3ka9",
  "seller_sku": "ACME-DOGFOOD-10LB",
  "title": "Acme Grain-Free Dog Food, 10 lb",
  "brand": "Acme",
  "category_id": "cat_pet_food",
  "status": "inactive",
  "barcode": "012345678905",
  "created_at": "2026-10-14T09:02:11Z",
  "updated_at": "2026-10-14T09:02:11Z"
}

The product starts inactive. The next two calls make it buyable.

3. Set the price

PUT /pricing/var_51hd02
Authorization: Bearer <your-api-key>
Idempotency-Key: price-var_51hd02-2026-10-14
Content-Type: application/json

{ "price": "24.99", "compare_at_price": "29.99", "currency": "USD" }

Response 200 (Pricing Endpoints)

{
  "variant_id": "var_51hd02",
  "product_id": "prod_8f3ka9",
  "seller_sku": "ACME-DOGFOOD-10LB",
  "price": "24.99",
  "compare_at_price": "29.99",
  "currency": "USD",
  "effective_from": "2026-10-14T09:03:02Z",
  "effective_to": null,
  "updated_at": "2026-10-14T09:03:02Z"
}

Money is a decimal string, never a JSON number: sending "price": 24.99 fails with 422. Field formats are defined in Data Types and Enums.

4. Record opening stock

POST /inventory/adjustments
Authorization: Bearer <your-api-key>
Idempotency-Key: receiving-2026-10-14-po-4471
Content-Type: application/json

{
  "variant_id": "var_51hd02",
  "location_id": "loc_memphis_01",
  "change": 140,
  "reason": "received",
  "note": "Opening stock"
}

Response 201

{
  "id": "mov_93jd71",
  "variant_id": "var_51hd02",
  "location_id": "loc_memphis_01",
  "change": 140,
  "reason": "received",
  "quantity_on_hand_after": 140,
  "created_at": "2026-10-14T09:04:45Z"
}

With a price set and stock recorded, set the product active with PATCH /catalog/products/prod_8f3ka9 and body { "status": "active" }.

5. List orders and page through them

GET /orders?status=confirmed&limit=2
Authorization: Bearer <your-api-key>

Response 200

{
  "data": [
    {
      "id": "ord_64kx20",
      "order_number": "AAP-2026-104821",
      "status": "confirmed",
      "placed_at": "2026-10-13T19:22:08Z",
      "total": "60.04",
      "currency": "USD"
    },
    {
      "id": "ord_31bb07",
      "order_number": "AAP-2026-104819",
      "status": "confirmed",
      "placed_at": "2026-10-13T18:47:55Z",
      "total": "24.99",
      "currency": "USD"
    }
  ],
  "next_cursor": "cur_ord31bb07_next"
}

Follow next_cursor until it is null (Pagination and Filtering (Pagination & Filtering))

GET /orders?status=confirmed&limit=2&cursor=cur_ord31bb07_next

In production, learn about orders from the order.created event instead of polling (Webhook Event Schemas); use this list to reconcile.

6. Acknowledge an order and ship it

POST /orders/ord_64kx20/acknowledge
Authorization: Bearer <your-api-key>
Idempotency-Key: ack-ord_64kx20

Response 200: the order object with "acknowledged_at": "2026-10-14T09:11:20Z". Then create the shipment, as in Orders Endpoints and Fulfillment Endpoints

POST /orders/ord_64kx20/fulfillments
Authorization: Bearer <your-api-key>
Idempotency-Key: ship-ord_64kx20-1
Content-Type: application/json

{
  "carrier": "UPS",
  "service": "Ground",
  "tracking_number": "1Z8842W90311884510",
  "lines": [ { "order_line_id": "line_01", "quantity": 2 } ]
}

Response 201: the shipment object with "status": "in_transit". If the first call times out, retry both calls with their same idempotency keys (Idempotency Keys): the recorded results come back and nothing is duplicated.

7. Handle a validation error

PUT /pricing/var_51hd02
Authorization: Bearer <your-api-key>
Content-Type: application/json

{ "price": 24.99, "currency": "USD" }

Response 422

{
  "error": {
    "code": "validation_failed",
    "message": "Field 'price' must be a decimal string with at most two decimal places."
  }
}

Fix the named field and resend. Check the response's rate-limit headers on every call while tuning a new integration (Rate Limit Headers).

8. Receive a webhook delivery

Your endpoint receives (Webhook Event Schemas)

POST /webhooks/aapawz
Pawz-Event: order.created
Pawz-Delivery: dlv_5120
Pawz-Signature: t=1760462528,v1=9f2c…

{
  "id": "evt_60rp18",
  "type": "order.created",
  "created_at": "2026-10-13T19:22:08Z",
  "account_id": "acct_7k2m9x",
  "data": {
    "order_id": "ord_64kx20",
    "order_number": "AAP-2026-104821",
    "status": "confirmed",
    "total": "60.04",
    "currency": "USD"
  }
}

Verify the signature over the raw body, record evt_60rp18 as handled, reply 200, then process. The signature value above is truncated for print; verify against the full header value.

9. Generate a client instead of hand-writing calls

The calls above correspond one-to-one with the machine-readable description of the API; see OpenAPI Spec for obtaining it and generating a typed client. Definitions of the terms used across these examples are in Glossary.

Idempotency Keys

OpenAPI Spec