Core Concepts

This guide is the shared vocabulary the other developer guides assume: the resources of a sale, identifiers, pagination, idempotency, errors, rate limits, and change over time. Learn it before you build; every domain guide: Catalog, Orders, Webhooks, Feeds and Bulk Data: builds on the terms set out here. The Overview states the same conventions in reference form.

The resources of a sale

The API is organized around the resources of a sale, in the order a sale moves

Resource	What it holds	Reference
Catalog	Products, variants, and their content	Catalog Endpoints
Inventory	Stock levels by product and location	Inventory Endpoints
Orders	Orders placed with your account, line by line	Orders Endpoints
Fulfillment	Shipments, tracking, and delivery state	Fulfillment Endpoints
Returns	Return requests, labels, and refunds in progress	Returns Endpoints
Payments	Charges, payouts, and payment state	Payments Endpoints
Pricing	Prices and price changes for your products	Pricing Endpoints
Analytics	Sales and performance reporting	Analytics Endpoints

Program-specific resources: standing and compliance records, brand and manufacturer functions, franchise functions, and veterinary and pharmacy functions: are available only to accounts in those programs; see Governance Endpoints, Brand and Manufacturer Endpoints, Franchise Endpoints, and Veterinary and Pharmacy Endpoints. Field and enum definitions shared across resources are collected in Data Types and Enums.

A product, its stock, its price, and the orders against it are separate resources with separate endpoints, on purpose: each changes on its own cadence, for its own reasons, and an integration updates each through its own resource rather than through side effects on another.

Identifiers

Every resource has an id: an opaque string assigned by the Platform.

• Treat ids as indivisible values: store them whole, compare them for equality, and pass them back unchanged. Do not parse, construct, sort by, or guess them.
• An id identifies a resource within your account's scope. An id copied from another account, another integration, or an example in this documentation will not resolve for your key.
• Your own references: your product codes, your order numbers: travel as fields on the resources you create, where the resource supports them, so you can match Platform records to your records without bending Platform ids into your numbering.

Formats

• JSON. Requests and responses are JSON, UTF-8 encoded. Send Content-Type: application/json on every request with a body.
• Timestamps. All timestamps are ISO 8601 in UTC, for example 2026-10-14T10:42:32Z. Store them as given; convert for display only.
• Money. Amounts are decimal strings accompanied by a currency field, for example "amount": "24.99", "currency": "USD". Never send or store floating-point numbers for money, and never assume a currency the response did not state.
• Unknown fields. Responses may gain fields as the API develops. Ignore fields you do not recognize rather than failing.

Pagination and filtering

Collection endpoints return one page at a time. A response carries the page of results and a cursor for the next page; pass the cursor back to continue, and stop when no cursor is returned. The mechanics are specified in Pagination and Filtering (Pagination & Filtering).

• Filter on the server using the parameters each collection documents: status, date range, and the like: rather than pulling pages to filter in your application. Pulling ten thousand records to keep ten is the most common performance failure in new integrations, and it is the one rate limits notice first.
• When you walk a collection, expect it to change underneath you: records are created and updated while you page. Design walks to tolerate seeing a record twice or not at all, and rely on each record's id to reconcile.
• For bulk replication: a full copy of your catalog or your orders: use the feed and export path in Feeds and Bulk Data, not repeated collection walks.

Idempotency

Any request that changes state must be safe to retry. Writes accept an idempotency key in the Idempotency-Key header

• Generate a fresh, unique value for each distinct write, and send the same value again when you retry that write: after a timeout, a connection failure, or a 5xx response, you often cannot know whether the first attempt was applied.
• A retry with the same key and the same body returns the original result instead of applying the write twice.
• Reusing a key for a different write is an error; treat it as a bug in your integration, not as a shortcut.
• Keep your keys long enough to cover your retry horizon. The full semantics are specified in Idempotency Keys.

This rule is what makes webhook handling, fulfillment submission, and refund issuance safe to build: delivery and retries are at-least-once throughout the Platform, and idempotency is how your side stays correct anyway.

Errors

A failed request returns a non-2xx status and a JSON error body

{"error": {"code": "…", "message": "…"}}

• The code is the machine-readable value to branch on; the message is for humans and logs. Codes and their meanings are listed in Error Codes.
• A 4xx means your request is wrong: the key, the scope, the id, or the body. Fix it; do not retry it unchanged.
• A 5xx means the failure is on the Platform side. Retry with exponential backoff and jitter, reusing the idempotency key on writes.
• Log the status, the code, and the request you sent for every failure. That trio is what support@aapawz.com will ask for, and what API Troubleshooting works from.

Rate limits

Requests are metered per key. Responses carry rate-limit headers that state your remaining budget; the limits and headers are specified in Rate Limit Headers, and compliance is a condition of access under the API Access Tiers.

• On 429, stop, honor the retry guidance in the response, and resume after the stated window with backoff. Retrying harder into a 429 extends the penalty and is a policy violation, not a technique.
• If you are hitting limits in steady state, you are polling where you should be subscribed (Webhooks) or walking collections where you should be using feeds (Feeds and Bulk Data). Change the design, not the retry rate.

Change over time

The API is not versioned by URL. Changes are additive wherever possible: new resources, new endpoints, and new response fields do not break existing integrations. A change that cannot be made additively is announced in advance in the Changelog, which is the authoritative record of what changed and when. Build clients that ignore unknown fields, avoid depending on undocumented behavior, and read the Changelog as part of maintaining your integration.