Pricing

This guide covers setting and reading prices through the API: how the price a buyer sees is the price you set, how changes take effect, how promotions differ from prices, and how to keep your prices correct when your costs change. Endpoint detail is in Pricing Endpoints. Prices connect to the rest of the system in two places: the catalog (Catalog) holds the products prices attach to, and orders (Orders) freeze the price as charged at purchase time.

Goal and prerequisites

Goal: every sellable product has exactly one current price: the price you intend: and a price change you make is the price buyers see, with no other system quietly recomputing it.

Prerequisites: products in the catalog with stable identifiers, an API key with pricing scope, and your own price decisions made in your system: the API records and applies prices; it does not decide your margins for you.

The one rule

The displayed price is the price of record. The price stored for a product through the pricing resource is the price the storefront shows and the price the buyer is charged. Nothing recomputes it at display time, and your integration must not compute display prices on its own side either: read the price of record and show it, or set a new price of record and let that be shown. Two systems computing "the price" by their own arithmetic will eventually disagree, and the buyer sees the disagreement. If a price looks wrong, the question is always "what price of record was set, and when": answerable from the pricing resource: never "what did some page calculate."

Step 1: Set a price

Set or update a product's price through Pricing Endpoints

POST https://www.aapawz.com/api/pricing
Authorization: Bearer <your-api-key>
Content-Type: application/json
Idempotency-Key: <a-unique-value-for-this-write>

{
  "product_id": "<product-id>",
  "amount": "24.99",
  "currency": "USD"
}

• Amounts are decimal strings with a currency (Overview). Never send floating-point numbers for money.
• Send every write with an Idempotency-Key (Idempotency Keys): concurrent or retried price writes must converge on one price of record, not stack into several.
• The response confirms the price now in effect. Store that confirmation: amount, currency, and the time it took effect: in your system against the product, so your records and the Platform's can be compared at reconciliation.

Field detail, including effective dating where the resource supports it, is in Pricing Endpoints and Data Types and Enums; complete calls are in Request and Response Examples.

Step 2: Change prices when your inputs change

Prices change when your costs, your freight, or your competitive position change. The working discipline

1. Compute the new price in your own system, by your own pricing decisions.
2. Send the result: the finished price, not the inputs to a formula. The API stores prices, not pricing recipes; a later reader sees the price that was in effect, not a reconstruction.
3. Verify by reading the price back through Pricing Endpoints after bulk changes, and reconcile your price list against the Platform's on a schedule (pagination per Pagination & Filtering).
4. A product with no current price cannot be sold. Treat "sellable product, no price" as an alert condition in your reconciliation, not as a curiosity.

Promotions are not price edits

A sale is not a price change, and the two mechanisms must never be substituted for each other

• The price of record is the everyday price. It changes when your pricing decision changes.
• A promotion is a time-bounded reduction: a percentage off, an amount off, a bundled offer: with its own conditions (eligible products, minimum spend, maximum discount, dates), applied at checkout against the price of record.

Never run a promotion by overwriting prices and restoring them afterward: the restore fails silently somewhere, the everyday price is lost, and the promotion becomes unauditable. Never bake a promotion into the price of record either, for the same reason in reverse. Where your account has promotion tooling, it is exercised through the resources and rules Pricing Endpoints and your Seller Center provide; the price stays the price, and the reduction is recorded as a reduction: which is also how Analytics can later tell you what the promotion actually did.

Subscription and repeat-delivery pricing follows the same separation: any subscriber reduction is an adjustment applied at checkout under its program's rules, never a second price of record for the same product.

Shipping and the displayed price

What a buyer pays for delivery follows your account's shipping terms and the Platform's checkout presentation; it is not a lever your integration pulls by editing prices. Do not inflate a product's price to mimic a shipping offer, and do not discount a price to mimic free delivery: both corrupt the price of record and mislead the buyer about what the product costs. Where a membership or program benefit changes what delivery costs the buyer, that benefit is applied by the Platform at checkout under its own rules, and the price of record is untouched.

Failure handling

• A price write succeeds but the storefront shows another figure: read the price of record back. If the record is what you sent, the display is showing a promotion adjustment or a stale cached view; if the record is not what you sent, another writer (a teammate, another of your systems, a bulk job) overwrote it. One writer per price is the fix: designate which of your systems owns pricing and silence the others.
• Duplicate or conflicting prices after a bulk job: your job retried without idempotency keys, or two jobs overlapped. Re-assert the intended price once, with a key, and read back to confirm convergence.
• 400 on a price write: malformed amount (a number instead of a decimal string is the classic), missing currency, or a product id that does not resolve under your account. Error Codes names the class.
• An order charged a price you do not recognize: the order's frozen line items (Orders) are what was charged; compare them against the price of record in effect at that timestamp from your confirmations before concluding anything is wrong. Prices changed after the purchase do not reach backward into it.

What good looks like

One system owns your prices; every change is a deliberate write with an idempotency key and a stored confirmation; promotions live in their own mechanism; reconciliation compares your list to the Platform's and finds nothing unexplained. Pricing is the most consequential data your integration touches: a wrong price either loses money on every sale or overcharges every customer: so the working rule is conservative: write carefully, read simply, and never improvise arithmetic at the edge.