Sales and shipping

The sales API exposes the seller-visible order, sold items, destination, and tracking information. The shipping API builds on those sale IDs to purchase labels asynchronously.

Reading sales

Use GET /api/public/v1/sales with sales:read. Results are ordered newest first by default. Each response includes:

• sale_id as a stable public UUID, plus order dates, payment state, shipment state, and cancellation state.
• Public item IDs and the receiving API key's external item IDs when available.
• Seller-visible item amounts.
• The seller-visible marketplace charge in marketplace_fee.
• Managed payout status, amount, method, eligibility time, and payment time when available.
• Shipping destination and tracking details when available.

The same public sale structure is used by sale.created, sale.updated, and shipment.tracking_updated webhooks.

Shipping prerequisites

• Batch shipping is enabled for the collector.
• The collector has at least one ship-from location.
• The auth token has the required shipping scopes.
• Every selected sale is currently ready for shipping.

Label creation sequence

1. Call GET /api/public/v1/shipping/ship-from-locations and select an origin, or rely on the default location.
2. Call GET /api/public/v1/shipping/eligible-sales for that location.
3. Select sales with ready_for_shipping: true.
4. Submit POST /api/public/v1/shipping-batches with a new external ID and the sale IDs.
5. Poll GET /api/public/v1/shipping-batches/{batchId} or wait for a terminal webhook.
6. When the availability flags become true, retrieve labels, pick list, and manifest URLs.

Eligibility can change between steps 2 and 4. Handle 400 by refreshing eligible sales before submitting another request.

Batch states

State	Required action
QUEUED	Wait or poll
IN_PROGRESS	Wait or poll
FINISHED	Download available documents
ACTION_REQUIRED	Inspect item errors and choose a recovery action
FAILED	Inspect the failure and retry eligible shipments when permitted

The detail response includes per-item PENDING, SUCCESS, or ERROR states.

Recovering a partial failure

If some labels succeeded and others failed:

• Retry failed shipments with POST /shipping-batches/{batchId}/retry and a new external ID, or
• Remove failed items with POST /shipping-batches/{batchId}/remove-failed-items to complete the successful portion and regenerate its documents.

Retry is available only when the original batch has failed shipments and its ship date is today. When it is no longer eligible for retry, refresh eligible sales and create a new batch. If every shipment failed, retry instead of removing all failed items.