Pricing Endpoints

This document covers the pricing endpoints: reading the current price of your products, setting and scheduling prices, and reading price history. The price a buyer sees is the price you set through these endpoints, stored as the product's current price and applied at checkout exactly as stored. Seller pricing obligations are governed by the Seller Pricing Policy.

Access through the developer API is issued by the Company and is limited by seller type: manufacturer and supplier accounts receive API access for importing data, under the Developer Agreement and the API Access Tiers. Price write endpoints require the import entitlement. Nothing in this document grants broader access.

Endpoints

Method	Path	Purpose	Access
GET	`/pricing`	List current prices for your variants, paginated	Any API key
GET	`/pricing/{variant_id}`	Read the current and scheduled prices for one variant	Any API key
PUT	`/pricing/{variant_id}`	Set the current price for a variant	Import entitlement
POST	`/pricing/{variant_id}/schedule`	Schedule a future price change	Import entitlement
DELETE	`/pricing/schedules/{id}`	Cancel a scheduled price change	Import entitlement
GET	`/pricing/{variant_id}/history`	List past prices for a variant, newest first	Any API key

All paths are relative to the base URL https://www.aapawz.com/api. Collections paginate as specified in Pagination and Filtering (Pagination & Filtering). Writes accept an Idempotency-Key header (Idempotency Keys): send one on every price change, so a retried write never applies twice.

The price object

{
  "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-01T00:00:00Z",
  "effective_to": null,
  "updated_at": "2026-10-01T09:14:22Z"
}

price is the amount the buyer pays, a decimal string with a currency field (Overview, Data Types and Enums). Send prices as strings; a JSON number for a price is rejected.
compare_at_price is the reference price shown struck through when it is higher than price. It must be a genuine former or list price for the same variant. Send null when no reference price exists: never set a reference price the product was not actually offered at.
A product with no current price, or a price of 0.00, is not offered for sale. Setting a price is one of the two steps that make a product buyable; the other is stock (Inventory Endpoints).
Prices are per variant. The product in Catalog Endpoints carries no price of its own; a buyer always pays a variant's price.

Setting a 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"
}

The new price takes effect immediately and returns 200 with the price object. The previous price closes (its effective_to is set) and remains readable in history. A price change never alters an order already placed (Orders Endpoints): the buyer pays the price in force when the order was placed.

Validation: price must be greater than zero, have at most two decimal places for USD, and be in the currency of your account. A compare_at_price lower than price is rejected with 422 and code compare_at_below_price.

Scheduling a price change

Schedule a sale or a price rise in advance

{
  "price": "19.99",
  "compare_at_price": "24.99",
  "currency": "USD",
  "effective_from": "2026-11-27T05:00:00Z",
  "effective_to": "2026-11-30T08:00:00Z"
}

The response is 201 with a schedule object carrying its own id. At effective_from the scheduled price becomes current; at effective_to, where set, the price reverts to the price it replaced. Schedules may not overlap for the same variant: an overlapping schedule fails with 409 and code schedule_conflict. Cancel a pending schedule with DELETE /pricing/schedules/{id}; a schedule already in effect cannot be cancelled, only replaced by a new price.

History and reconciliation

GET /pricing/{variant_id}/history returns every price the variant has carried, with its effective period: the audit record for a pricing dispute. Payments for a sale always use the price in the history row covering the order's placement time (Payments Endpoints).

Errors

Status	Code	Cause
404	`not_found`	No variant or schedule with that identifier exists in your account
409	`schedule_conflict`	The scheduled period overlaps an existing schedule
422	`validation_failed`	Price missing, not a decimal string, or with too many decimal places
422	`compare_at_below_price`	`compare_at_price` is below `price`
422	`invalid_period`	`effective_to` is not after `effective_from`

Error bodies follow Error Codes.

Payments Endpoints

Analytics Endpoints