Orders API

REST API endpoints for browsing and managing orders.

List Orders

GET /api/v1/orders

Returns a paginated list of orders, sorted by creation date (newest first).

Query Parameters

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "orderNumber": 1042,
      "status": "completed",
      "totalAmount": "5000",
      "currency": "usd",
      "locale": "en-US",
      "customer": {
        "id": "0191abc0-0000-7000-8000-000000000010",
        "email": "jane@example.com",
        "name": "Jane Doe"
      },
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 42
  }
}

Get Order

GET /api/v1/orders/:id

Returns the full order with line items, customer info, shipping address, and payment details.

The orderData snapshot is a copy of the cart, so each lineItems[].productVariant in it arrives with the merchant-private fields blanked — cost, digital, externalId, supplierAliases, reservedQuantity and unavailableQuantity. This endpoint also reads orders that are not paid yet (bank transfer, cash on delivery), so a paid download's files are never in the response; the buyer receives them as encrypted links once the payment is recorded. See Merchant-private fields.

Response

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "orderNumber": 1042,
  "status": "completed",
  "totalAmount": "5000",
  "currency": "usd",
  "locale": "en-US",
  "lineItems": [
    {
      "id": "0191abc0-0000-7000-8000-000000000100",
      "productVariantId": "0191abc0-0000-7000-8000-000000000200",
      "quantity": 2,
      "unitPrice": "2500",
      "product": {
        "name": "Classic Tee",
        "slug": "classic-tee"
      }
    }
  ],
  "customer": {
    "id": "0191abc0-0000-7000-8000-000000000010",
    "email": "jane@example.com",
    "name": "Jane Doe"
  },
  "shippingAddress": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  },
  "paymentInstructions": null,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Cash on delivery

An order placed with cash on delivery (paymentProvider: "cashOnDelivery") is created unpaid: the courier collects the money and the merchant marks it paid afterwards. While the payment is still outstanding, paymentInstructions carries the merchant's note for the shopper, so a storefront can repeat it on its own order page:

{
  "paymentProvider": "cashOnDelivery",
  "paymentInstructions": "Exact change, please - the courier carries no cash."
}

It turns null once the payment is recorded (orderData.paymentCollectedAt is set), when the merchant has left no instructions, and on every order paid by any other provider.

Language

locale is the language version of the store the order was placed on (en-US, pl-PL, …), copied from the cart at checkout. Every email about the order renders in it. null for orders placed before the storefront reported a language, imports and orders created in the admin — those fall back to the store's default storefront language.

Prices and tax

Every money field in an order's orderData snapshot is net, exactly like the live catalog's. Gross twins are returned alongside them, so a storefront prints a past order the same way it prints a cart:

The line variants carry the full set of twins described in Prices and tax (originalPriceGross, calculatedPriceGross, and so on). They are computed from the tax rate frozen into the snapshot — each line from its own product's rate, delivery from the shipping method's — never from the product's current rate, which may have changed since. shipping.priceGross is the listed delivery charge; whether the order actually earned free delivery is already settled in the order's totals.

Both GET /api/v1/orders and GET /api/v1/orders/:id return them.

Update Order

PATCH /api/v1/orders/:id

Updates an order's fulfillment status and/or tracking information, or corrects the contact email the order was placed with.

Request Body

The response echoes the order's email alongside id, status, trackingNumber, shipment, billingAddress and shippingAddress.

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "trackingNumber": "1Z999AA10123456784"
  }' \
  https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001

Contact Email

email corrects this order only. The customer record and any shopper account keep their own address, so a typo caught after checkout can be fixed without touching the customer's profile.

Two cases are rejected with 409:

• The order has no customer attached – there is nothing to email, so correct its addresses instead.
• A KSeF e-invoice has already been filed for the order – the filed invoice is the record of the buyer.

Customer Notifications

Only two statuses email the buyer, and a real transition into one of them sends the same email the admin dashboard triggers:

processing and canceled still record the status change and fire the store events, but they notify nobody – there is no customer template for them. The shipped and delivered emails only go out when the store has that email event enabled at /manage/emails, and they carry the order's tracking number and link when one is known, whether it came with this request or was stored earlier. Retrying the same status update does not re-send the notification.

Order Statuses

Create Shipment

POST /api/v1/orders/:id/shipment

Creates a carrier shipment for the order. The carrier is resolved from the order's shipping method (its linked shipping addon) – you don't specify the carrier in the request. The store's environment (live/test) determines whether the carrier's sandbox or production API is used.

Request Body

All fields are optional. The request body can be empty – every field has a server-side default or returns a 422 explaining what's missing.

InPost Fields

GLS Fields

Passing fields that belong to the other carrier returns 400 – e.g. sending weightKg for an InPost order is rejected.

# InPost shipment
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"template": "medium"}' \
  https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001/shipment

# GLS shipment (empty body – uses defaults)
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001/shipment

Response (201)

InPost:

{
  "carrier": "inpost",
  "shipmentId": "123456789",
  "status": "created",
  "trackingNumber": null,
  "labelReady": false,
  "template": "medium",
  "templateSource": "explicit"
}

GLS:

{
  "carrier": "gls",
  "shipmentId": "987654321",
  "parcelNumbers": ["12345678901"],
  "trackId": "T12345",
  "trackingUrl": "https://gls-group.eu/track/T12345",
  "labelReady": true,
  "labelWarning": null
}

Error Responses

Get Shipment

GET /api/v1/orders/:id/shipment

Returns the current shipment status for an order.

Response (200)

InPost:

{
  "carrier": "inpost",
  "shipmentId": "123456789",
  "status": "confirmed",
  "trackingNumber": "620123456789012345678901",
  "trackingUrl": "https://inpost.pl/sledzenie-przesylek?number=620123456789012345678901",
  "labelReady": true
}

GLS:

{
  "carrier": "gls",
  "shipmentId": "987654321",
  "parcelNumbers": ["12345678901"],
  "trackId": "T12345",
  "trackingUrl": "https://gls-group.eu/track/T12345",
  "labelReady": true
}

Error Responses

Delete Shipment

DELETE /api/v1/orders/:id/shipment

Deletes the shipment for an order. Only supported for GLS – InPost shipments must be cancelled in the InPost Parcel Manager.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001/shipment

Response (200)

{
  "ok": true,
  "deleted": 1
}

Error Responses

Get Shipment Label

GET /api/v1/orders/:id/shipment/label

Downloads the shipping label as a file. Returns the raw file (PDF, ZPL, or EPL) with appropriate Content-Type and Content-Disposition headers.

Query Parameters

# Download PDF label
curl -H "Authorization: Bearer your_api_key" \
  -o label.pdf \
  https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001/shipment/label

# Download ZPL for thermal printer (InPost only)
curl -H "Authorization: Bearer your_api_key" \
  -o label.zpl \
  "https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001/shipment/label?format=zpl"

Error Responses

Customer Orders

GET /api/v1/customers/:id/orders

Returns orders for a specific customer, paginated.

Query Parameters

Response

{
  "items": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "orderNumber": "1042",
      "status": "completed",
      "totalCents": 5000,
      "currency": "usd",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 8,
    "offset": 0,
    "limit": 20,
    "hasMore": false
  }
}

List Refunds

GET /api/v1/orders/:id/refunds

Returns the refunds recorded against an order, newest first.

Query Parameters

curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001/refunds

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-00000000000a",
      "orderId": "0191abc0-1234-7def-8000-000000000001",
      "stripeRefundId": "re_3Abc123",
      "amount": 2500,
      "currency": "usd",
      "reason": "requested_by_customer",
      "reasonNote": "Customer changed their mind",
      "status": "succeeded",
      "refundType": "partial",
      "refundApplicationFee": false,
      "restockItems": true,
      "shippingAmount": null,
      "createdAt": "2024-05-02T10:00:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}

Create Refund

POST /api/v1/orders/:id/refunds

Issues a refund against the order's original payment. The order's own payment provider decides how it is processed: PayNow orders refund through PayNow, everything else through Stripe. Providers this API cannot refund on your behalf are refused with a 400 – see Payment Providers below.

Body Parameters

Each lineItems entry takes lineItemIndex (position in the order), productVariantId, quantity, and amount in cents.

Restocking is bounded by the order itself. A line is restocked up to the quantity the order contains for that variant – asking for more restocks only the ordered quantity – and a line naming a variant the order does not contain is ignored. Ignored lines do not fail the request: the refund is already recorded and the money has moved.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "reason": "requested_by_customer",
    "refundType": "partial",
    "restockItems": true
  }' \
  https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001/refunds

Payment Providers

Errors

Only orders with status paid, processing, shipped, completed, or partially_refunded can be refunded.

Remaining headroom counts committed refunds – both succeeded and pending rows. A refund still awaiting its provider's settlement webhook already consumes headroom, so amount plus every committed refund on the order may not exceed the order total.

Get Refund

GET /api/v1/orders/:id/refunds/:refundId

Returns a single refund belonging to the order.

curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/orders/0191abc0-1234-7def-8000-000000000001/refunds/0191abc0-1234-7def-8000-00000000000a