# Next Commerce: Admin API

> The REST Admin API and its guides: orders and external checkout, subscriptions, fulfillment, and exports. Operations are listed by tag; the versioned OpenAPI file is the contract.

This is one of 6 domain bundles derived from the platform capability map at https://developers.nextcommerce.com/capabilities.json (generated 2026-09-03). The other bundles are listed at https://developers.nextcommerce.com/llms.txt. Merchant and operator guides are on https://docs.nextcommerce.com; the changelog is https://docs.nextcommerce.com/changelog. The Admin API contract is the OpenAPI file at https://developers.nextcommerce.com/api/admin/2024-04-01.yaml.

## Capabilities

### Admin API (id: admin-api)

The REST Admin API manages store resources: products, orders, customers, subscriptions, fulfillment, payments, campaigns, and more. Access is by OAuth app token against https://{store}.29next.store/api/admin/, with the version selected per request by the X-29next-API-Version header. 2024-04-01 is the stable version; 2023-02-10 is deprecated; unstable carries in-progress changes.

Status: available. Audiences: developer. Links verified: 2026-09-03.

Caveats:
- The developer portal has no changelog of its own; version history is on the merchant changelog.
- There is no consolidated migration guide between API versions yet.

Merchant and operator guides (docs.nextcommerce.com):
- https://docs.nextcommerce.com/docs/build-a-store/technical-settings/configure-webhooks
- https://docs.nextcommerce.com/changelog

Developer guides (developers.nextcommerce.com):
- https://developers.nextcommerce.com/docs/admin-api
- https://developers.nextcommerce.com/docs/admin-api/permissions
- https://developers.nextcommerce.com/docs/admin-api/guides/exports

Admin API operations, version 2024-04-01 (12):
- [GET /store/ — Retrieve general business information and store settings.](https://developers.nextcommerce.com/docs/admin-api/reference/store/storeDetail)
- [GET /exports/ — Retrieve a list of exports.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsList)
- [POST /exports/ — Create a new export.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsCreate)
- [GET /exports/types/ — Retrieve all available export types.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsTypesRetrieve)
- [GET /exports/{id}/ — Retrieve an export.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsRetrieve)
- [GET /exports/{id}/download/ — Retrieve the download URL for a completed export file.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsDownloadRetrieve)
- [GET /metadata/ — Retrieve a list of metadata definitions.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataList)
- [POST /metadata/ — Create a new metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataCreate)
- [GET /metadata/{id}/ — Retrieve a metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataRetrieve)
- [PUT /metadata/{id}/ — Update an existing metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataUpdate)
- [PATCH /metadata/{id}/ — Partial update an existing metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataPartialUpdate)
- [DELETE /metadata/{id}/ — Delete an existing metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataDestroy)

Webhook events (2):
- [export.created](https://developers.nextcommerce.com/docs/webhooks/reference/exports/export.created)
- [store.updated](https://developers.nextcommerce.com/docs/webhooks/reference/store/store.updated)

AI agent skills:
- [next-ops-scan](https://github.com/NextCommerceCo/skills/tree/main/next-ops-scan)

### Orders and external checkout (id: orders)

Orders can be created through the Admin API from an external checkout (cart, order, upsell flow) and managed afterwards: fulfil, refund, capture, cancel, and edit. Campaign and storefront orders land in the same orders list.

Status: available. Audiences: merchant, developer. Links verified: 2026-09-03.

Merchant and operator guides (docs.nextcommerce.com):
- https://docs.nextcommerce.com/docs/manage/orders/collect-payments-on-orders
- https://docs.nextcommerce.com/docs/manage/orders/test-orders

Developer guides (developers.nextcommerce.com):
- https://developers.nextcommerce.com/docs/admin-api/guides/external-checkout
- https://developers.nextcommerce.com/docs/admin-api/guides/order-management

Admin API operations, version 2024-04-01 (30):
- [GET /orders/ — Retrieve a list of orders.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersList)
- [POST /orders/ — Create a new order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCreate)
- [GET /orders/{number}/ — Retrieve a order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRetrieve)
- [PUT /orders/{number}/ — Update an existing order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersUpdate)
- [PATCH /orders/{number}/ — Partial update an existing order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersPartialUpdate)
- [POST /orders/{number}/add-line-items/ — Add additional items to the order and charge the initial order payment method.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersAddLineItemsCreate)
- [POST /orders/{number}/cancel/ — Cancel an existing order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCancelCreate)
- [POST /orders/{number}/capture/ — Captures the total amount of the previously authorized funds for this order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCaptureCreate)
- [POST /orders/{number}/collect-payment/ — Collect payment for an order outstanding balance on the order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCollectPaymentCreate)
- [GET /orders/{number}/fulfillment-orders/ — Retrieves a list of fulfillment orders for a specific order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentOrdersRetrieve)
- [GET /orders/{number}/fulfillments/ — Retrieve order fulfillments.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentsRetrieve)
- [POST /orders/{number}/fulfillments/ — Add shipment order for separate line.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentsCreate)
- [GET /orders/{number}/fulfillments/{fulfillmentId}/ — Retrieve an existing order fulfillment.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentRetrieve)
- [GET /orders/{number}/fulfillments/{fulfillmentId}/events/ — Retrieve a list of fulfillment events of a order fulfillment.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentsEventsList)
- [POST /orders/{number}/fulfillments/{fulfillmentId}/events/ — Create a fulfillment event in an existing order fulfillment.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentsEventsCreate)
- [GET /orders/{number}/fulfillments/{fulfillmentId}/events/{eventId}/ — Retrieve a fulfillment event.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentsEventsRetrieve)
- [DELETE /orders/{number}/fulfillments/{fulfillmentId}/events/{eventId}/ — Delete an existing fulfillment event.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentsEventsDestroy)
- [POST /orders/{number}/lines/ — Add a new line item to an existing order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesCreate)
- [PATCH /orders/{number}/lines/{lineId}/ — Update an existing line item in an order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesPartialUpdate)
- [DELETE /orders/{number}/lines/{lineId}/ — Remove a line item from an existing order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesDestroy)
- [POST /orders/{number}/mark-as-paid/ — Marks an order as paid.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersMarkAsPaidCreate)
- [GET /orders/{number}/notes/ — Retrieve a list of all order notes in an existing order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersNotesList)
- [POST /orders/{number}/notes/ — Create an order note in an existing order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersNotesCreate)
- [POST /orders/{number}/refund/ — Refund an existing order.](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRefundCreate)
- [POST /orders/{number}/refund/calculate/](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRefundCalculateCreate)
- [GET /carts/ — Retrieve a list of all open carts.](https://developers.nextcommerce.com/docs/admin-api/reference/carts/cartsList)
- [POST /carts/ — Create a new cart.](https://developers.nextcommerce.com/docs/admin-api/reference/carts/cartsCreate)
- [GET /carts/{id}/ — Retrieve a cart.](https://developers.nextcommerce.com/docs/admin-api/reference/carts/cartsRetrieve)
- [PUT /carts/{id}/ — Update an existing cart.](https://developers.nextcommerce.com/docs/admin-api/reference/carts/cartsUpdate)
- [DELETE /carts/{id}/ — Delete an existing cart.](https://developers.nextcommerce.com/docs/admin-api/reference/carts/cartsDestroy)

Webhook events (3):
- [order.created](https://developers.nextcommerce.com/docs/webhooks/reference/orders/order.created)
- [order.updated](https://developers.nextcommerce.com/docs/webhooks/reference/orders/order.updated)
- [cart.abandoned](https://developers.nextcommerce.com/docs/webhooks/reference/carts/cart.abandoned)

### Subscriptions (id: subscriptions)

Native recurring orders. Merchants configure phases, statuses, pause, cancellation paths, decline salvage, and account updater in the dashboard; developers create and manage subscriptions through the Admin API. Renewals are not a separate webhook: a renewal surfaces as transaction.created (and order.created) with billing_cycle set.

Status: available. Audiences: merchant, developer. Links verified: 2026-09-03.

Caveats:
- There is no subscription.renewed event. Detect renewals from transaction.created with billing_cycle.

Merchant and operator guides (docs.nextcommerce.com):
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide/managing-subscriptions
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide/subscription-phases
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide/subscription-statuses
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide/subscription-settings
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide/pause-subscriptions
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide/cancellation-paths
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide/decline-salvage
- https://docs.nextcommerce.com/docs/manage/subscriptions-guide/account-updater
- https://docs.nextcommerce.com/docs/analytics/subscription-performance

Developer guides (developers.nextcommerce.com):
- https://developers.nextcommerce.com/docs/admin-api/guides/subscription-management

Admin API operations, version 2024-04-01 (13):
- [GET /subscriptions/ — Retrieve a list of subscriptions.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsList)
- [POST /subscriptions/ — Create a new subscription.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsCreate)
- [GET /subscriptions/{id}/ — Retrieve a subscription.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsRetrieve)
- [PATCH /subscriptions/{id}/ — Partial update an existing subscription.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPartialUpdate)
- [POST /subscriptions/{id}/cancel/ — Cancel an existing subscription.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsCancelCreate)
- [POST /subscriptions/{id}/lines/ — Create a new subscription line.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesCreate)
- [PUT /subscriptions/{id}/lines/{lineId}/ — Update an existing subscription line.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesUpdate)
- [DELETE /subscriptions/{id}/lines/{lineId}/ — Delete a subscription line in an existing subscription line.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesDestroy)
- [POST /subscriptions/{id}/pause/ — Pause an existing subscription.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPauseCreate)
- [POST /subscriptions/{id}/renew/ — Trigger a subscription renewal order.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsRenewCreate)
- [POST /subscriptions/{id}/resume/ — Resume a paused subscription.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsResumeCreate)
- [POST /subscriptions/{id}/retry/ — Trigger a renewal payment retry for a subscription.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsRetryCreate)
- [GET /subscriptions/{id}/transactions/ — Retrieve a list of transactions in an existing subscription.](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsTransactionsList)

Webhook events (3):
- [subscription.created](https://developers.nextcommerce.com/docs/webhooks/reference/subscriptions/subscription.created)
- [subscription.updated](https://developers.nextcommerce.com/docs/webhooks/reference/subscriptions/subscription.updated)
- [transaction.created](https://developers.nextcommerce.com/docs/webhooks/reference/payments/transaction.created)

AI agent skills:
- [next-bulk-subscription](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-subscription)

### Fulfillment (id: fulfillment)

Orders are fulfilled through locations, fulfillment statuses, and location-based routing. Apps can register as a fulfillment service and receive assigned fulfillment orders through the Admin API.

Status: available. Audiences: merchant, developer. Links verified: 2026-09-03.

Merchant and operator guides (docs.nextcommerce.com):
- https://docs.nextcommerce.com/docs/features/fulfillment-guide
- https://docs.nextcommerce.com/docs/features/fulfillment-guide/fulfillment-statuses
- https://docs.nextcommerce.com/docs/features/fulfillment-guide/location-based-routing
- https://docs.nextcommerce.com/docs/features/fulfillment-guide/advanced-settings
- https://docs.nextcommerce.com/docs/start-here/get-started/fulfillment-settings

Developer guides (developers.nextcommerce.com):
- https://developers.nextcommerce.com/docs/apps/guides/fulfillment-service

Admin API operations, version 2024-04-01 (26):
- [GET /assigned-fulfillment-orders/ — Retrieve assigned fulfillment order requests](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/assignedFulfillmentOrdersList)
- [GET /fulfillment-orders/ — Retrieve a list of fulfillment orders.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentOrdersList)
- [GET /fulfillment-orders/{id}/ — Retrieve a fulfillment order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentOrdersRetrieve)
- [GET /fulfillment-orders/{id}/available-locations/ — Retrieve available locations for a Fulfillment Order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/availableLocationsRetrieve)
- [POST /fulfillment-orders/{id}/cancel/ — Cancel fulfillment order](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentOrdersCancel)
- [POST /fulfillment-orders/{id}/cancellation-request/ — Sends a fulfillment cancellation request to the fulfillment service.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/cancellationRequestSend)
- [POST /fulfillment-orders/{id}/cancellation-request/accept/ — Accepts a fulfillment cancellation request sent to a fulfillment service for a fulfillment order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/cancellationRequestAccept)
- [POST /fulfillment-orders/{id}/cancellation-request/cancel/ — Cancel a requested fulfillment cancellation request.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/cancellationRequestCancel)
- [POST /fulfillment-orders/{id}/cancellation-request/reject/ — Rejects a fulfillment cancellation request sent to a fulfillment service for a fulfillment order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/cancellationRequestReject)
- [POST /fulfillment-orders/{id}/close/ — Marks an processing fulfillment order as incomplete](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentOrdersClose)
- [POST /fulfillment-orders/{id}/fulfillment-request/ — Sends a fulfillment request to the fulfillment service of a fulfillment order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentRequestSend)
- [POST /fulfillment-orders/{id}/fulfillment-request/accept/ — Accepts a fulfillment request sent to a fulfillment service for a fulfillment order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentRequestAccept)
- [POST /fulfillment-orders/{id}/fulfillment-request/cancel/ — Cancel Requested Fulfillment Order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentRequestCancel)
- [POST /fulfillment-orders/{id}/fulfillment-request/reject/ — Rejects a fulfillment request sent to a fulfillment service for a fulfillment order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentRequestReject)
- [GET /fulfillment-orders/{id}/fulfillments/ — Retrieve Fulfillments for a Fulfillment Order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentsRetrieve)
- [POST /fulfillment-orders/{id}/fulfillments/ — Create Fulfillments for a Fulfillment Order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentsCreate)
- [POST /fulfillment-orders/{id}/hold/ — Hold Fulfillment.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentOrdersHold)
- [POST /fulfillment-orders/{id}/move/ — Move location of a fulfillment order.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentOrdersMove)
- [POST /fulfillment-orders/{id}/release-hold/ — Release On Hold Fulfillment.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentOrdersReleaseHold)
- [GET /locations/ — Retrieve a list of all configured fulfillment locations.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/locationsList)
- [POST /locations/ — Create a new fulfillment location.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/locationsCreate)
- [GET /locations/{id}/ — Retrieve an existing fulfillment location.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/locationsRetrieve)
- [PUT /locations/{id}/ — Update an existing fulfillment location.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/locationsUpdate)
- [DELETE /locations/{id}/](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/locationsDestroy)
- [GET /shipping-methods/ — Retrieve a list of all configured shipping methods.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/shippingMethodsList)
- [GET /shipping-methods/{id}/ — Retrieve an existing shipping method.](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/shippingMethodsRetrieve)

Webhook events (2):
- [fulfillment.created](https://developers.nextcommerce.com/docs/webhooks/reference/fulfillment/fulfillment.created)
- [fulfillment.updated](https://developers.nextcommerce.com/docs/webhooks/reference/fulfillment/fulfillment.updated)

AI agent skills:
- [next-bulk-fulfill](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-fulfill)
- [next-bulk-move](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-move)

## Pages

The full text of every developer page cited above, in the order listed.

# Admin API (https://developers.nextcommerce.com/docs/admin-api)

### Getting Started [#getting-started]

At the core of Next Commerce, the Admin API lets developers manage store resources, integrate third-party services, and build seamless external order flows.

### Authentication [#authentication]

The Admin API uses the OAuth 2 authorization protocol to manage access to your store's resources. OAuth apps and associated access tokens can be tailored with object-level permissions to ensure that each integrated service only has access to the objects it needs.

Before using the Admin API, you'll need to create a store and an OAuth app for API access. To create an OAuth app, navigate to **Settings > API Access** and create a new OAuth app with the applicable [permissions](https://developers.nextcommerce.com/docs/admin-api/permissions) to retrieve your **Access Token**. It is recommended to create unique OAuth apps for each external system so you can revoke access as needed.

```bash title="Admin API Path"
https://{store}.29next.store/api/admin/
```

> **Note (Why 29next?):** Next Commerce was formerly 29 Next, and the platform still carries that name in its core technical identifiers: store and account hostnames (`{store}.29next.store`, `accounts.29next.com`), the `X-29next-API-Version` and `X-29Next-Signature` headers, and the API key namespace. These are current, in use on every store, and not scheduled to change. Use them exactly as written.

**Use your OAuth app access token in the request headers to access the API.**

```bash title="Example Request"
curl -X GET "https://{store}.29next.store/api/admin/" \
-H "Authorization: Bearer <api access token>" \
-H "X-29next-API-Version: 2024-04-01"
```

> **Warning (Do NOT publish or share Admin API authentication tokens):** Admin API tokens provide full access to your system, including the ability to perform destructive actions like deleting data or users. These tokens should never be shared publicly or exposed in client-side code.
> 
>   **Always keep your Admin API tokens private and secure.**

### Versioning [#versioning]

API versioning allows Next Commerce to continuously evolve the platform while maintaining predictable behavior for existing APIs with a path for upgrades and deprecations.

**Admin API Versions**

| Version      | Status               | Docs                                                                     |
| ------------ | -------------------- | ------------------------------------------------------------------------ |
| `2023-02-10` | Deprecated (legacy)  | [View Reference](https://developers.nextcommerce.com/docs/admin-api/reference/2023-02-10/orders/ordersList) |
| `2024-04-01` | Stable (recommended) | [View Reference](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersList)            |
| `unstable`   | Unstable             | [View Reference](https://developers.nextcommerce.com/docs/admin-api/reference/unstable/orders/ordersList)   |

**Specify an API Version**

To specify a version, pass the `X-29next-API-Version` header with your desired API version.

> **Warning:** It is **highly recommended** to specify your version on your API requests to ensure consistency for your integration.

### Rate Limits [#rate-limits]

Admin APIs are rate-limited to maintain the stability and equity of our platform for all users. We employ a number of methods to enforce rate limits.

| API       | Rate Limit Method | Limit             |
| --------- | ----------------- | ----------------- |
| Admin API | Request-based     | 4 requests/second |

> **Note:** Once you reach API rate limits you'll then receive a 429 Too Many Requests response, and a message that a throttle has been applied.

We recommend that API users limit calls appropriately, cache results, and retry requests using industry best practices to avoid rate-limit errors.


# Permissions (https://developers.nextcommerce.com/docs/admin-api/permissions)

Admin API access is controlled granularly by Scopes that are associated with each OAuth App and associated Access Tokens.

| Scope                       | Detail                                                                    |
| --------------------------- | ------------------------------------------------------------------------- |
| `admin:read`                | Access to list and view all data                                          |
| `admin:write`               | Access to create and update all data                                      |
| `campaigns:read`            | Access to list and view campaigns                                         |
| `campaigns:write`           | Access to create and update campaigns                                     |
| `carts:read`                | Access to list and view carts                                             |
| `carts:write`               | Access to create and update carts                                         |
| `catalogue:read`            | Access to list and view catalogue objects such as products and categories |
| `catalogue:write`           | Access to create and update catalogue related objects                     |
| `content:read`              | Access to list and view storefront content related objects                |
| `content:write`             | Access to create and update storefront content related objects            |
| `disputes:read`             | Access to list and view disputes                                          |
| `disputes:write`            | Access to create and update disputes                                      |
| `exports:read`              | Access to list and view all exports                                       |
| `exports:write`             | Access to create and update exports                                       |
| `fulfillment_service:read`  | Access to list assigned fulfillment orders and own locations              |
| `fulfillment_service:write` | Access to create fulfillment locations and fulfillments                   |
| `fulfillment_orders:read`   | Access to list fulfillment order fulfillment requests                     |
| `fulfillment_orders:write`  | Access to update fulfillment order fulfillment requests                   |
| `gateways:read`             | Access to list and view all gateways and gateway groups                   |
| `gift_cards:read`           | Access to list and view all gift cards                                    |
| `gift_cards:write`          | Access to create and update gift cards                                    |
| `locations:read`            | Access to list and view all locations                                     |
| `locations:write`           | Access to create and update locations                                     |
| `metadata:read`             | Access to list and view all metadata definitions                          |
| `metadata:write`            | Access to create and update metadata definitions                          |
| `orders:read`               | Access to list and view all orders                                        |
| `orders:write`              | Access to create and update orders                                        |
| `store:read`                | Access to list and view store                                             |
| `subscriptions:read`        | Access to list and view all subscriptions                                 |
| `subscriptions:write`       | Access to create and update subscriptions                                 |
| `themes:read`               | Access to list and view all themes                                        |
| `themes:write`              | Access to create and update themes                                        |
| `transactions:read`         | Access to list and view all transactions                                  |
| `transactions:write`        | Access to create and update transactions                                  |
| `tickets:read`              | Access to list and view all tickets                                       |
| `tickets:write`             | Access to create and update tickets                                       |
| `users:read`                | Access to list and view all users                                         |
| `users:write`               | Access to create and update users                                         |
| `webhooks:read`             | Access to list and view all webhooks                                      |
| `webhooks:write`            | Access to create and update webhooks                                      |


# API Exports (https://developers.nextcommerce.com/docs/admin-api/guides/exports)

The Exports API allows you to generate and download bulk data exports from your store as CSV files. This is useful for reporting, analytics, reconciliation, and data migration workflows.

> **Note:** Exports are processed asynchronously. After creating an export, you'll need to poll for completion before downloading the file.

### Export Flow [#export-flow]

```mermaid
sequenceDiagram
    autonumber
    App->>Store: Subscribe to export.created webhook
    App->>Store: Create export via API
    Store->>Store: Export processing
    Store->>App: export.created webhook event
    App->>Store: Download export file
```

Creating and downloading an export is a 3-step process:

1. Subscribe to the `export.created` [webhook event](https://developers.nextcommerce.com/docs/webhooks) to be notified when exports are ready.
2. Create a new export using the [exportsCreate](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsCreate) endpoint with your desired type and date range.
3. When you receive the `export.created` webhook, download the file using the [exportsDownloadRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsDownloadRetrieve) endpoint.

### Available Export Types [#available-export-types]

Use the [exportsTypesRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsTypesRetrieve) endpoint to list all available export types, or reference the table below.

| Type                      | Description             |
| ------------------------- | ----------------------- |
| `order_list`              | Orders                  |
| `order_line_items`        | Order Line Items        |
| `customer_list`           | Customers               |
| `transaction_list`        | Transactions            |
| `dispute_list`            | Disputes                |
| `subscription_list`       | Subscriptions           |
| `subscription_line_items` | Subscription Line Items |
| `open_cart_list`          | Open Carts              |
| `open_cart_line_items`    | Open Cart Line Items    |
| `return_list`             | Returns                 |
| `return_line_items`       | Return Line Items       |
| `fulfillment_list`        | Fulfillments            |
| `fulfillment_line_items`  | Fulfillment Line Items  |

### Create an Export [#create-an-export]

To create a new export, send a POST request to the [exportsCreate](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsCreate) endpoint with the export `type` and date range.

```json title="__http:POST:https://{store}.29next.store/api/admin/exports/"
{
  "type": "order_list", // export type
  "date_from": "2025-01-01T00:00:00Z", // start of date range
  "date_to": "2025-03-31T23:59:59Z" // end of date range
}
```

The response returns the export object with a `pending` status.

```json title="Create Export Response"
{
  "id": 42,
  "created_at": "2025-04-01T12:00:00Z",
  "type": "order_list",
  "status": "pending",
  "date_from": "2025-01-01T00:00:00Z",
  "date_to": "2025-03-31T23:59:59Z",
  "url": "https://{store}.29next.store/api/admin/exports/42/"
}
```

### Poll Export Status [#poll-export-status]

After creating an export, poll the [exportsRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsRetrieve) endpoint until the `status` changes from `pending` to `available`.

```json title="__http:GET:https://{store}.29next.store/api/admin/exports/{id}/"
{
  "id": 42,
  "created_at": "2025-04-01T12:00:00Z",
  "type": "order_list",
  "status": "available", // export is ready to download
  "date_from": "2025-01-01T00:00:00Z",
  "date_to": "2025-03-31T23:59:59Z",
  "url": "https://{store}.29next.store/api/admin/exports/42/"
}
```

> **Warning:** Avoid polling too frequently. Checking every couple of minutes is sufficient for pending exports. For a more efficient approach, subscribe to the `export.created` [webhook event](https://developers.nextcommerce.com/docs/webhooks) to be notified immediately when an export is available for download.

### Download Export File [#download-export-file]

Once the export status is `available`, use the [exportsDownloadRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsDownloadRetrieve) endpoint to get a download URL for the CSV file.

```json title="__http:GET:https://{store}.29next.store/api/admin/exports/{id}/download/"
{
  "url": "https://example.com/media/{store}/export_csv/{file_name}.csv?signature" // signed download
}
```

> **Warning:** Download URLs are temporary signed URLs. Fetch the file promptly after retrieving the URL. If the URL expires, request a new one from the download endpoint.

### Export Webhooks [#export-webhooks]

Subscribe to the `export.created` [webhook event](https://developers.nextcommerce.com/docs/webhooks) to be notified immediately when an export is available for download. The webhook payload includes the export object data, allowing you to proceed directly to downloading the file without additional API calls.

> **Tip:** Using the `export.created` webhook is the recommended approach for automated export workflows. It eliminates the need for polling and ensures you download the file as soon as it's ready.

### List Exports [#list-exports]

Use the [exportsList](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsList) endpoint to retrieve previous exports with optional filtering by type and creation date.

```json title="__http:GET:https://{store}.29next.store/api/admin/exports/"
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 42,
      "created_at": "2025-04-01T12:00:00Z",
      "type": "order_list",
      "status": "available",
      "date_from": "2025-01-01T00:00:00Z",
      "date_to": "2025-03-31T23:59:59Z",
      "url": "https://{store}.29next.store/api/admin/exports/42/"
    }
  ]
}
```

> **Note:** The list endpoint uses cursor-based pagination. Use the `next` and `previous` URLs in the response to navigate through results.


# External Checkout Flow (https://developers.nextcommerce.com/docs/admin-api/guides/external-checkout)

In this guide we'll cover the best practices when building an external checkout flow using the Next Commerce Admin API. Using the API gives you the most flexibility of data and functionality across the platform and external integrations.

```mermaid
stateDiagram-v2
    direction LR
    cart: Create Cart
    order: Create Order
    upsell: Add Upsell
    cart --> order
    order --> upsell
    upsell --> Confirmation
```

### Create Cart [#create-cart]

Carts are the starting point for all orders, carts are essentially draft orders waiting to be converted into orders. Creating the cart is a vital step in capturing leads and setting up abandoned cart flows.

```json title="__http:POST:https://{store}.29next.store/api/admin/carts/"
{
    "lines": [
        {
            "product_id": 1,
            "currency": "USD",
            "quantity": 1,
            "price": 33.44 // optional
        }
    ],
    "user": {
        "email": "johndoe@gmail.com",
        "first_name": "John",
        "last_name": "Doe",
        "language": "en",
        "ip": "1.1.1.1",
        "accepts_marketing": true,
        "user_agent": "Mozilla/5.0..."
    },
    "attribution": {
        "funnel": "Funnel Offer V2",
        "metadata": {
            "custom_meta_field": "Custom meta data"
        }
    }
}
```

> **Note (Notes):** * The carts create API accepts a user object that will `get or create` the user by their email address making it is safe to use for both new and existing users.
>   * Attribution added to a cart is carried over to the Orders and Subscriptions created on the users next order, you do not need to pass this data on the order request.
>   * If you need to capture an address with the cart, use the [usersAddressesCreate](https://developers.nextcommerce.com/docs/admin-api/reference/customers/usersAddressesCreate) endpoint which will create a default address for the user.

### Create Order [#create-order]

Creating an order is the core resource in an external checkout flow, see the example below to familiarize yourself with the [ordersCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCreate) API endpoint.

```json title="__http:POST:https://{store}.29next.store/api/admin/orders/"
{
    "lines": [
        {
            "product_id": 1,
            "currency": "USD",
            "quantity": 1,
            "price": "5.99" // optional custom price
        }
    ],
    "user":{
        "email": "johndoe@gmail.com"
    },
    "shipping_code": "default",
    "shipping_price": "5.48",
    "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "line1": "9975 Berkshire Dr.",
        "line4": "Monsey",
        "postcode": "10952",
        "phone_number": "2025550140",
        "state": "NY",
        "country": "US"
    },
    "billing_same_as_shipping_address": true,
    "payment_method": "card_token",
    "payment_details": {
        "card_token": "test_card"
    }
}
```

> **Note (Notes):** * Complete User detail is not necessary if the user already exists, you can reference an existing user by `id` or by `email`.
>   * Attribution detail are not necessary if you have already added it to the users active cart.
>   * `shipping_code` and `shipping_price` are optional parameters you can set to specify the shipping method and shipping price.
>   * If you already created an address for the user, pass `use_default_shipping_address` and `use_default_billing_address` as true to use their default address for the order.
>   * For additional payment methods, see the [Payment Methods](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods) guides — [Bankcard](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/bankcard), [3DS2](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/bankcard#3d-secure-3ds2), [Apple Pay](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/apple-pay), [PayPal](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/paypal), [Klarna](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/klarna), [Affirm](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/affirm), [Afterpay](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/afterpay), [Twint](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/twint), [Swish](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/swish), [Bancontact](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/bancontact), and [SEPA](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/sepa-debit).

### Add Upsells [#add-upsells]

Add additional products (line items) to the original order through the [ordersAddLineItemsCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersAddLineItemsCreate) API. Adding items to the order will automatically re-use the order's initial payment method to collect payment for the additional products.

```json title="__http:POST:https://{store}.29next.store/api/admin/orders/{number}/add-line-items/"
{
  "lines": [
        {
            "product_id": 2,
            "currency": "USD",
            "quantity": 1,
            "price": "10.33" // optional custom price
        }
    ]
}
```

> **Warning:** The `ordersAddLineItemsCreate` API requires that the order initial **payment method** supports merchant initiated charges. Current supported payment methods are `bankcard` and `paypal` (with Reference Transactions enabled).

### Cart / Order / Upsell lines Detail [#cart--order--upsell-lines-detail]

Cart, Order, and Upsell line items represent the products the customer is purchasing. When an order is created, the product fulfillment location will be automatically chosen based on product stock records and inventory availability.

```json title="Specify Line Items and Currency"
{
    "lines": [
        {
            "product_id": 1, // ensure variant ID and not parent product ID
            "currency": "USD",
            "quantity": 1,
            "price": "33.44" // optional custom price
        }
    ]
}
```

> **Tip:** Ensure you use the variant product ID for order line items. &#x2A;*Single variant products still contain a variant product future product management to add additional variants.**

#### Subscription Line Items [#subscription-line-items]

Lines also accept an optional `subscription` object to specify a subscription that will be automatically created after the initial order is successfully created.

```json title="Subscription Line Items"
"lines": [
    {
        "product_id": 1,
        "currency": "USD",
        "quantity": 1,
        "price": "5.99", // optional custom initial price
        "subscription": {
            "interval": "day", // day, month, year
            "interval_count": 30,  // interval counter, ie 30 days
            "price": "24.99" // optional custom recurring price
        }
    }
]
```

> **Tip:** Subscription line items have two `price` fields available. The order line item level `price` and then the subscription object `price`. Passing price points in these fields enables you to easily achieve an "initial order discount".

> **Warning:** Orders with Subscription line items **must have an initial payment** (order total > 0.00) to validate and retain the bankcard for future usage.

#### Custom Line Item Properties [#custom-line-item-properties]

Lines accept an optional `properties` object of key/value pairs to capture customization details for personalized or made-to-order products, such as an engraving, monogram, or gift message. The values are stored on the line item and persist to the created order (and to the subscription line item when the line creates a subscription).

```json title="Custom Line Item Properties"
"lines": [
    {
        "product_id": 1,
        "quantity": 1,
        "properties": {
            "engraving": "Best Dad Ever",
            "font": "Serif",
            "gift_message": "Happy Birthday!"
        }
    }
]
```

> **Note:** Line item `properties` are used to determine the uniqueness of line item products and flow all the way through to fulfillment order line items for customized product fulfillment.

### Cart / Order User Detail [#cart--order-user-detail]

The `user` object on carts/orders represents the **customer** which includes their contact details.  Below are the recommended fields to pass for the user for ease of use and support of external integrations that may rely on the data, i.e. `user_agent`.

> **Note:** Users are first checked for an existing user by `email` before creating a new user. Successive `cartsCreate` and `ordersCreate` API requests with the same user details will reference the same user.

```json title="User Detail"
"user":{
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@gmail.com",
    "phone_number": "+18125879988", // optional, E.164 format required
    "language": "en", // used for localized email notifications
    "accepts_marketing": true, // used by external integrations
    "ip": "123.123.123.123", // used by external integrations
    "user_agent": "Mozilla/5.0..." // used by external integrations
}
```

> **Warning:** **It is not recommended to pass `phone_number` directly on the user when creating a cart or order, we recommend passing a local phone number in the `shipping_address` instead.** Address fields have country context, which allows local phone numbers to be passed and converted to [E.164 format](https://en.wikipedia.org/wiki/E.164) before being saved. A `phone_number` passed to the `user` object directly must be in E.164 format.

### Cart / Order Attribution Detail [#cart--order-attribution-detail]

Cart and Order `attribution` object sets the [marketing attribution](https://docs.nextcommerce.com/docs/features/offers/marketing-attribution) on the order for tracking the source of orders and use in orders reporting. You can also pass in [metadata](https://docs.nextcommerce.com/docs/build-a-store/technical-settings/metadata-fields-and-tags) fields that are configured on the store to track custom attribution parameters and integrate external tracking platforms.

```json title="Attribution Detail"
"attribution": {
    "funnel": "Funnel Offer V2",
    "metadata": {
        "custom_meta_field": "Custom meta data"
    }
}
```

### Order Shipping Detail [#order-shipping-detail]

```json title="Shipping Detail"
"shipping_code": "default",
"shipping_price": "5.48",
```

The `shipping_code` is an optional field to specify the Shipping Method to be used for the order, **if not passed, the cheapest Shipping Method will be used**.  `shipping_price` is also optional and provides a way to override the configured price for the Shipping Method of the order allowing you to discount or charge an upsell for shipping on the order.

### Order Addresses Detail [#order-addresses-detail]

The `shipping_address` object on the order represents the address where the order will be shipped, and similarly for the `billing_address`. The first `shipping_address` and `billing_address` created for a user is automatically set as their default shipping and billing address, [see API Reference](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCreate).

> **Tip:** Use `billing_same_as_shipping_address` to forego having to pass a full duplicate address for `billing_address`.

```json title="Address Detail"
"shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "line1": "9975 Berkshire Dr.",
    "line4": "Monsey", // city
    "postcode": "10952",
    "phone_number": "2025550140",
    "state": "NY",
    "country": "US"
},
"billing_same_as_shipping_address": true,
```

> **Note:** * User `phone_number` is automatically saved from the user's first address if they do not have an existing `phone_number`.
>   * In a "Two Step" flow where the customer address is collected before creating the order, create an address for the user and then pass the `use_default_shipping_address` and `use_default_billing_address` as true on the `orders_create` request.

### Order Payment Detail [#order-payment-detail]

The order `payment_method` and `payment_details` objects work in tandem to specify the payment method for the order and provide any additional data that may be required per payment method.

The example below uses a [Test Card Token](https://developers.nextcommerce.com/docs/admin-api/guides/testing-guide) to create a **Test Order**.

```json title="Payment Detail"
"payment_method": "card_token",
"payment_details": {
    "card_token": "test_card", // See iFrame Payment Form Guide
    "statement_descriptor": "BRANDNAME" // See details below
},
```

To route the order to a specific gateway or gateway group, include `payment_gateway` or `payment_gateway_group` (an id, never both) inside `payment_details`. See [Gateway Routing](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/bankcard#gateway-routing) in the Bankcard guide.

#### Statement Descriptor [#statement-descriptor]

Merchants have the option to pass a custom `statement_descriptor` on orders so the end customer will more easily recognize the charge on their card bank statement. Using this field will override all subsequent transactions for the bankcard, even across payment gateways.

> **Note (Statement Descriptor Validation):** Descriptors can be up to 22 alphanumeric characters, spaces, and these special characters: `& , . - #`.  Passing in an invalid statement descriptor will be ignored.

#### Payment Method Guides [#payment-method-guides]

See the [**Payment Methods**](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods) section for method-specific guides on creating orders, plus the full capability matrix (flow type, express checkout, upsell, and subscription support per method).

**[View all payment methods →](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods)**


# API Order Management (https://developers.nextcommerce.com/docs/admin-api/guides/order-management)

Order management operations can be automated through the Admin API for more efficient operations and bulk actions on large quanities of orders.

Below are best practices and guides for common scenarios merchants and partners use to manage orders on the Admin API.

### Order Items Editing [#order-items-editing]

Editing items on an order is common practice, such as swapping products purchased for a different size or color with the same value without needing to collect payment or create a refund.

> **Note (Only Available on 2024-04-01 API Version):** Order editing APIs are only available on 2024-04-01 API Version and above, if you are still using older versions we recommend you upgrade your integration.
> 
>   Order editing APIs also do not affect order payment within each request. To remove items with an associated refund, see [order refunds](#order-refunds). Using order edit APIs can result in the customer owing or the merchant owing to the customer.

#### Line Item Quantities Explained [#line-item-quantities-explained]

Order line items have 4 quantity attributes that represent quantities at different states in an order life cycle.

* `quantity` - Item quantity total ever added to the order in this line.
* `current_quantity` - Current item quantity that have not yet been removed.
* `fulfillable_quantity` - Item quantity that have not yet been fulfilled, such as a partial fulfillment.
* `editable_quantity` - Item quantity that currently can be edited.

```json title="Line Item Quantities Explained"
"lines": [
  {
    ...
    "quantity": 3, // quantity of items ever added
    "current_quantity": 2, // current quantity that have not been removed
    "fulfillable_quantity": 1, // quantity that have not yet been fulfilled
    "editable_quantity": 1, // quantity that can be edited
    ...
  }
]
```

### Swap Items Flow [#swap-items-flow]

```mermaid
stateDiagram-v2
    direction LR
    lines: Retrieve Order Lines
    removeLine: Remove Unwanted Items
    addLine: Add New Items
    collectPayment: Collect Payment
    lines --> removeLine
    removeLine --> addLine
    addLine --> collectPayment
```

Swapping Items on an order is a 4 step process:

1. Retrieve order line items using the [ordersRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRetrieve) endpoint and check `editable_quantity` is > 0.
2. Update/Remove line items using the [ordersLinesPartialUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesPartialUpdate) or [ordersLinesDestroy](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesDestroy) endpoint.
3. Create new line item [ordersLinesCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesCreate) endpoint.
4. [Collect payment for an outstanding](#collect-payment-for-outstanding-balance) balance using the [ordersCollectPaymentCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCollectPaymentCreate) endpoint.

#### Update Existing Line Item [#update-existing-line-item]

Below is an example API call to change the quantity of a line item to 1. If the existing quantity was 2, this would remove 1 quantity, can also be used to increase line item quantity. This endpoint only accepts quantity changes, to change the product or price, see [ordersLinesCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesCreate) endpoint.

```json title="__http:PATCH:https://{store}.29next.store/api/admin/orders/{number}/lines/{lineID}/"
{
  "quantity": 1, // change quantity to 1
  "reason": "product swap" // optional
}
```

#### Remove Full Line Item [#remove-full-line-item]

Below is an example DELETE request to the [ordersLinesDestroy](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesDestroy) endpoint to remove a line item.

```json title="__http:DELETE:https://{store}.29next.store/api/admin/orders/{number}/lines/{lineID}/"
{}
```

> **Note (Check Line Item Editable Quantity):** Line items have `editable_quantity` which represents the item quantity not already in process of being fulfilled, already fulfilled, or  already removed from the order.
> 
>   **If `editable_quantity` is `0`, the line item cannot be edited.**

#### Create New Line Item [#create-new-line-item]

Below is an example POST request to the [ordersLinesCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersLinesCreate) endpoint to create a new line item.

```json title="__http:POST:https://{store}.29next.store/api/admin/orders/{number}/lines/"
{
  "product_id": 184, // product variant id
  "quantity": 1,
  "price": 89.99, // optional
  "reason": "product swap" // optional
}
```

#### Collect Payment for Outstanding Balance [#collect-payment-for-outstanding-balance]

Orders can have an outstanding balance owed by the customer as a result of changing items on the order. To collect the outstanding balance, use the [ordersCollectPaymentCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCollectPaymentCreate) endpoint to initate a payment transaction with the order's initial payment method.

```json title="__http:POST:https://{store}.29next.store/api/admin/orders/{number}/collect-payment/"
{
  "send_payment_notification": true // optionally send notificaiton to customer
}
```

### Order Refunds [#order-refunds]

Order management actions that require refunding and removing items from an order can be done through the refund flow. The refund flow is espcially useful when creating partial refunds or creating refunds for items that have already shipped to the customer.

#### Refund Flow [#refund-flow]

```mermaid
stateDiagram-v2
    direction LR
    lines: Retrieve Order Lines
    calculate: Calculate Refund
    refundCreate: Create Refund
    lines --> calculate
    calculate --> refundCreate
```

Refunding specific items of an order is a 3-step process:

1. Retreive order line items using the [ordersRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRetrieve) endpoint.
2. Calculate the refund using the [ordersRefundCalculateCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRefundCalculateCreate) endpoint.
3. Create the refund using the [ordersRefundCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRefundCreate) endpoint.

> **Note:** Order Refund Calculate APIs are only available on `2024-04-01` version and newer. See [API Versioning](https://developers.nextcommerce.com/docs/admin-api#versioning) for how to specify a version in your requests.

#### Retrieve Order Lines [#retrieve-order-lines]

Below is an abreviated example request to [ordersRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRetrieve) endpoint to get the line items of the order.

```json title="__http:GET:https://{store}.29next.store/api/admin/orders/{number}/"
{
  "lines": [
    {
      "id": 1000, // order line item
      "quantity": 3, // quantity in the order
      "current_quantity": 3 // quantity available and not yet removed from the order
    }
  ]
}
```

> **Warning (Order Payments Must Be Captured):** Order payments must be captured in order to create partial refunds, uncaptured payments cannot be partially refunded.

#### Calculate Refund [#calculate-refund]

Call the [ordersRefundCalculateCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRefundCalculateCreate) endpoint with your line items to calculate the refund and see which initial payment transactions will be refunded.

```json title="__http:POST:https://{store}.29next.store/api/admin/orders/{number}/refund/calculate/"
{
  "refund_lines": [
    {
      "line_id": 1000, // line item we want to refund
      "quantity": 1 // quantity to refund
    }
  ],
  "refund_shipping": {
    "full_refund": false, // set true to fully refund shipping
    "amount_excl_tax": "3.99"
  }
}
```

Below is the response from the [ordersRefundCalculateCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRefundCalculateCreate)  API that has been slightly abbreviated to focus on the relevant refund items.

```json title="Refund Calculate Response"
{
  "refund_lines": [
    {
      "line_id": 1000, // line item being refunded
      "quantity": 1, // number of items being refunded
      "restock_type": "no_restock", // restock action, see notes
      "refundable_quantity": 1, // items that can be refunded
      "amount_excl_tax": "59.99", // amount to be refunded excl tax
      "amount_incl_tax": "59.99", // amount to be refunded incl tax
      "total_tax": "0.00" // total tax on this line item to refund
    }
  ],
  "refund_shipping": {
    "amount_incl_tax": "3.99", // amount to be refunded incl tax
    "amount_excl_tax": "3.99", // amount to be refunded excl tax
    "total_tax": "0.00", // shipping tax to be refunded
    "refundable_amount": "4.99" // shipping amount avialable to refund
  },
  "transactions": [
    {
      "id": 1000, // transaction the refund will be allocated to, can be multiple.
      "amount": "63.98", // amount being refunded on this transaction
      "refundable_amount": "184.96" // amount available to refund with this transaction
    }
  ],
  "amount_excl_tax": "63.98", // total amoutn excl tax being refunded
  "amount_incl_tax": "63.98", // total amount incl to be refunded
  "total_tax": "0.00", // total tax being refunded
  "currency": "USD"
}
```

#### Create Refund [#create-refund]

We're now ready to create a refund using the [ordersRefundCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersRefundCreate) endpoint, see request details below.

```json title="__http:POST:https://{store}.29next.store/api/admin/orders/{number}/refund/"
{
  "note": "Example reason for the refund",
  "refund_lines": [
    {
      "line_id": 1000, // line item being refunded
      "quantity": 1, // number of items being refunded
      "restock_type": "no_restock", // restock action (from calculate step)
    }
  ],
  "refund_shipping": {
    "amount_excl_tax": "3.99",
    "full_refund": false
  },
  "send_refund_notification": true, // send refund email notification to customer
  "transactions": [
    {
      "id": 1000,  // transaction id to refund (from calculate step)
      "amount": "63.98" // amount to refund to this transaction (from calculate step)
    }
  ]
}
```

> **Note (Restock Actions):** Depending on the product type and status of the line items being refunded, there are differen't restock actions available.
> 
>   **Physical Product**
> 
>   * If unfulfilled, restock\_type must be `cancel`.
>   * If fullfilled, restock\_type can be `return` or `no_restock`.
> 
>   **Digital Product**
> 
>   * If unfulfilled, restock\_type must be `cancel`.
>   * If fulfilled, restock\_type must be `no_restock`.

### Update Shipping Address [#update-shipping-address]

Updating an order shipping address is a common task that can be done with a PATCH request to the [ordersUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersUpdate) endpoint.

```json title="__http:PATCH:https://{store}.29next.store/api/admin/orders/{number}/"
{
  "shipping_address": {
    "line1": "4765 Test Lane West", // new shipping address line 1
    "line4": "Mountain Pass", // new shipping address city
    "state": "CA", // new shipping address state
    "postcode": "92366", // new shipping address postcode
    "country": "US" // new shipping address country
  }
}
```

> **Note (Before Fulfillment Processing):** Updating an order shipping address should be done **before** the order is sent to a fulfillment location for fulfillment. If the order has already been accepted and processing, send a a [cancellationRequestSend](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/cancellationRequestSend) request and then [fulfillmentRequestSend](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentRequestSend) after you've updated the shipping address.

### Request Fulfillment [#request-fulfillment]

Fulfillment can be requested immediately through the [fulfillmentRequestSend](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentRequestSend) for cases that you'd like to immediately send the fulfillment order to the fulfillment location for fulfillment.

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/fulfillment-request/"
{
  "fulfillment_order_line_items": [  // will split the fulfillment order into a new fulfillment order
    {
      "id": 0,
      "quantity": 1
    }
  ],
  "message": "Special message to warehouse", // message to the fulfillment location
  "notify": true // notify the customer when fulfillment order is fulfilled
}
```

### Hold Fulfillment [#hold-fulfillment]

Holding fulfillment for an order while waiting for additional review or making adjustments to the order before sending to the fulfillment location for shipping.

```mermaid
stateDiagram-v2
    direction LR
    retrieveFulfillmentOrders: Retrieve Fulfillment Orders
    sendFulfillmentCancelRequest: Send Fulfillment Cancel Request
    retrieveFulfillmentOrders --> sendFulfillmentCancelRequest
```

1. Retrieve all fulfillment Orders using the [ordersFulfillmentOrdersRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentOrdersRetrieve) endpoint.
2. Send a [fulfillmentOrdersHold](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentOrdersHold) request for each fulfillment order to hold.

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/hold/"
{
  "reason": "address_incorrect", // see available reasons in api reference
  "reason_message": "Additional relevant detail." // provide additional relevant detail
}
```

### Cancel Fulfillment [#cancel-fulfillment]

Canceling a fulfillment order that is already accepted and processing with a fulfillment location is a common order management task to stop fulfillment or as a prerequisite step to moving a fulfillment order to a new location.

```mermaid
stateDiagram-v2
    direction LR
    retrieveFulfillmentOrders: Retrieve Fulfillment Orders
    sendFulfillmentCancelRequest: Send Fulfillment Cancel Request
    retrieveFulfillmentOrders --> sendFulfillmentCancelRequest
```

1. Retrieve all fulfillment Orders using the [ordersFulfillmentOrdersRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersFulfillmentOrdersRetrieve) endpoint.
2. Send a [cancellationRequestSend](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/cancellationRequestSend) request for each fulfillment order to request fulfillment cancellation.

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/cancellation-request/"
{
  "message": "Reason why canceling fulfillment" // message sent to the fulfillment location
}
```

### Move Fulfillment Orders [#move-fulfillment-orders]

### Add Fulfillment Tracking [#add-fulfillment-tracking]

Adding tracking information to a fulfillment order marks it as fulfilled and optionally notifies the customer with shipment tracking details. Use the [fulfillmentsCreate](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentsCreate) endpoint to create a fulfillment with tracking info.

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/fulfillments/"
{
  "notify": true, // send the customer an order shipped notification email
  "tracking_info": [
    {
      "tracking_code": "EXAMPLECODE",
      "carrier": "dhl_ecommerce"
    }
  ]
}
```

> **Note (Multiple Tracking Numbers):** The `tracking_info` field accepts an array, allowing you to add multiple tracking numbers for a single fulfillment order when a shipment is split across multiple packages.

### Cancel Order [#cancel-order]

Canceling an order is a common order management task when you need to cancel the entire order and refund all payment transactions. To cancel an order, send a request to the [ordersCancelCreate](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersCancelCreate) endpoint.

```json title="__http:POST:https://{store}.29next.store/api/admin/orders/{number}/cancel/"
{
  "cancel_reason": "Customer wants to cancel", // Appropiate cancel reason message
  "full_refund": true, // Refund all remaining payments or not
  "send_cancel_notification": true // Send the customer a notification or not
}
```


# API Subscription Management (https://developers.nextcommerce.com/docs/admin-api/guides/subscription-management)

Subscriptions management can be done through Admin API to automate business processes and perform bulk operations.

> **Note:** Subscription management actions most often times will only affect future renewals orders/charges of the subscription.

### Create Subscription [#create-subscription]

Subscriptions can be created directly through the [subscriptionsCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsCreate) Admin API endpoint for scenarios such as custom order flows or importing subcriptions from another platform.

```json title="__http:POST:https://{store}.29next.store/api/admin/subscriptions/"
{
    "lines": [ // subscription line item products and pricing
        {
            "product_id": 123,
            "quantity": 1,
            "currency": "USD",
            "price": "19.99"
        }
    ],
    "shipping_code": "default-shipping", // shipping method for renewal orders
    "shipping_price": "3.99", // shipping price for renewal orders
    "interval": "day", // subscription renewal interval
    "interval_count": 30, // subscription renewal interval count
    "next_renewal_date": "2022-2-28T08:41:37+07:00", // first renewal date
    "user": {
        "email": "john@smiths.com", // get or create a customer based on email address
        "first_name": "John",
        "last_name": "Smith"
    },
    "use_default_billing_address": true, // alternatively pass full billing_address
    "use_default_shipping_address": true, // alternatively pass full shipping_address
    "payment_method": "card_token",
    "payment_details": {
        "card_token": "<Card Token>" // see card tokenization iFrame guide
    },
}
```

### Updating Products & Pricing [#updating-products--pricing]

Updating subscription recurring items and pricing can be done through [subscriptionLinesCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesCreate), [subscriptionLinesUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesUpdate), and [subscriptionsLinesDestroy](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesDestroy) endpoints.

**Adding an Additional Product**

To add a new product to a subscription, use the [subscriptionLinesCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesCreate) Admin API endpoint with the product, price, and quanity details.

```json title="__http:POST:https://{store}.29next.store/api/admin/subscriptions/{id}/lines/"
{
  "price": "9.99", // recurring price for the product
  "product_id": 100, // product ID
  "quantity": 1 // quantity of the product
}
```

**Updating an Existing Line Item Product Price**

To update and existing product price and quantity on a subscription line, use the [subscriptionsLinesUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesUpdate) Admin API endpoint with the new price, and new quanity details.

```json title="__http:PUT:https://{store}.29next.store/api/admin/subscriptions/{id}/lines/{lineId}/"
{
  "price": "9.99", // new recurring price for the product
  "quantity": 1 // new quantity of the product
}
```

**Removing a Product**

To remove a product from a subscription, send a DELETE request to the [subscriptionsLinesDestroy](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsLinesDestroy) endpoint to remove the line item (ie the product) from future renewal orders created from the subscription.

```json title="__http:DELETE:https://{store}.29next.store/api/admin/subscriptions/{id}/lines/{lineId}/"
{}
```

> **Warning:** Subscriptions must have at least one line item with a product, you can alternatively cancel the subscription to stop all future renewals.

### Updating Renewal Schedule [#updating-renewal-schedule]

Changing the renewal schedule of a subscription can be achived with a PATCH request to the [subscriptionsPartialUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPartialUpdate) endpoint with a new `interval` and `interval_count`, ie 30 days.

```json title="__http:PATCH:https://{store}.29next.store/api/admin/subscriptions/{id}/"
{
    "interval": "day",
    "interval_count": 30,
    "next_renewal_date": "2025-06-29T03:28:59.193252-05:00" // optional next renewal date
}
```

### Changing Next Renewal Date [#changing-next-renewal-date]

Changing the next renewal date of a subscription can be achieved through updating the `next_renewal_date` key on the subscription object with a PATCH request to the [subscriptionsPartialUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPartialUpdate) endpoint with your new renewal date and time.

```json title="__http:PATCH:https://{store}.29next.store/api/admin/subscriptions/{id}/"
{
    "next_renewal_date": "2025-06-29T03:28:59.193252-05:00" // next renewal date & time
}
```

> **Tip:** If you would like to immediately renew the subscription, you can pass a date from the past and the subscription will process a renewal attempt within the next 30 minutes.

### Triggering a Renewal [#triggering-a-renewal]

To immediately trigger a renewal order for an active subscription, use the [subscriptionsRenewCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsRenewCreate) endpoint. This creates a new renewal order on demand without waiting for the next scheduled renewal date.

```json title="__http:POST:https://{store}.29next.store/api/admin/subscriptions/{id}/renew/"
{}
```

The endpoint returns the full subscription object with updated renewal details on success.

> **Warning:** The subscription must be in an `active` status to trigger a renewal. For subscriptions in `past_due` status, use the [subscriptionsRetryCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsRetryCreate) endpoint instead.

### Identifying Subscription Charges [#identifying-subscription-charges]

When a `transaction.created` webhook is associated with a subscription, `data.subscription` contains the subscription ID and billing cycle:

```json title="Subscription Transaction"
{
    "event_type": "transaction.created",
    "data": {
        "id": 10416,
        "subscription": {
            "id": 12345,
            "billing_cycle": 3
        }
    }
}
```

* `billing_cycle: 0` identifies the initial subscription charge.
* `billing_cycle: 1` identifies the first renewal.
* Each subsequent renewal increments the value by one.

The subscription object is empty when the transaction is not associated with a subscription.

### Updating Payment Details [#updating-payment-details]

Updating the Payment Gateway of a subscription can done through the [subscriptionsPartialUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPartialUpdate) endpoint.

**Changing Payment Gateway**

To change the payment gateway used for bankcard payments of a subscription, send a PATCH request to the [subscriptionsPartialUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPartialUpdate) endpoint with the new `payment_gateway`.

```json title="__http:PATCH:https://{store}.29next.store/api/admin/subscriptions/{id}/"
{
    "payment_details": {
        "payment_gateway": 23 // new payment gateway to be used on the next renewal
    }
}
```

**Updating Bankcard Payment Method**

To change the bankcard on a subscription, pass a new `card_token` with a PATCH request to the [subscriptionsPartialUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPartialUpdate) endpoint.

> **Note:** To update a bankcard on a subscription, you must use the &#x2A;*[iFrame to tokenize](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/bankcard)** the bankcard and use the `card_token` when updating the subscription itself.
> 
>   The new bankcard will be automatically verfied with a `verify` request to a payment gateway to ensure the new bankcard is valid and can be used for future renewals. If the bankcard cannot be verified, the update request will fail and return an error.

**New Bankcard Payment Method Flow**

```mermaid
stateDiagram-v2
    direction LR
    tokenize: Tokenize Bankcard
    request: Send PATCH Request
    verify: New Bankcard Verified
    updated: Subscription Updated
    tokenize --> request
    request --> verify
    verify --> updated
```

```json title="__http:PATCH:https://{store}.29next.store/api/admin/subscriptions/{id}/"
{
    "payment_details": {
        "card_token": "<New Card Token>", // new card token
        "payment_gateway": 23 // optionally pass a specific gateway
    },
    "billing_address": {
        "country": "US", // optionally pass a new billing address
        "first_name": "John",
        "last_name": "Doe",
        "line1": "123 East West St.",
        "line4": "New York",
        "state": "NY",
        "postcode": "90210"
    }
}
```

### Retrying Renewal [#retrying-renewal]

Subscriptions that are `past_due` status can be attemted to retry the renewal, often combined with a new `payment_gateway`, by using the [subscriptionsRetryCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsRetryCreate) endpoint.

```json title="__http:POST:https://{store}.29next.store/api/admin/subscriptions/{id}/retry/"
{
  "payment_gateway": 122 // optional new payment gateway to retry with
}
```

> **Tip:** The subscription retry endpoint is useful for custom recovery logic when attempting to recover failing subscriptions.

### Pause [#pause]

To temporarily stop renewals on an active subscription without cancelling it, use the [subscriptionsPauseCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPauseCreate) endpoint. Pausing is useful for win-back flows, customer-requested holds, or pausing a cohort during inventory or fulfillment issues.

```json title="__http:POST:https://{store}.29next.store/api/admin/subscriptions/{id}/pause/"
{
  "pause_until": "2026-08-01" // optional date (YYYY-MM-DD) to auto-resume on
}
```

If `pause_until` is omitted the subscription is paused indefinitely and will be auto-cancelled if it is not resumed within 6 months. The endpoint returns the full subscription object with status `paused` and the `paused_at` / `paused_until` timestamps populated.

> **Note:** Paused subscriptions skip all scheduled renewals until the `pause_until` date is reached, at which point renewals resume automatically on the existing schedule.

To resume a paused subscription before its `pause_until` date — or to reactivate an indefinitely paused subscription — use the [subscriptionsResumeCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsResumeCreate) endpoint with a future `next_renewal_date`.

```json title="__http:POST:https://{store}.29next.store/api/admin/subscriptions/{id}/resume/"
{
  "next_renewal_date": "2026-06-15" // required, must be a future date
}
```

### Cancel [#cancel]

To cancel a subscription, use the [subscriptionsCancelCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsCancelCreate) endpoint to stop all future renewals.

```json title="__http:POST:https://{store}.29next.store/api/admin/subscriptions/{id}/cancel/"
{
  "cancel_reason": "not_satisfied_with_product", // required
  "cancel_reason_other_message": "Wasn't happy with result", // optional
  "send_cancel_notification": true // to send the cancelation email or not
}
```

### Bulk Subscription Actions [#bulk-subscription-actions]

> **Tip:** The [`/next-bulk-subscription`](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-subscription) skill in the Next Commerce AI skills repo wraps this workflow — CSV ingestion, dry-run validation, rate limiting, and results reporting for bulk pauses, cancellations, renewal-date shifts, and other subscription updates — for Claude Code, Cursor, and other AI coding agents.

For operations that affect a cohort of subscriptions, iterate the endpoint that matches the subscription action: use [subscriptionsPauseCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPauseCreate) for pauses, [subscriptionsCancelCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsCancelCreate) for cancellations, and [subscriptionsPartialUpdate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPartialUpdate) for field updates such as renewal dates, cadence, addresses, or payment gateway details. Respect the **4 requests/second rate limit** (sleep \~0.26s between calls) and write each response to a log file so failures can be retried without re-running the whole batch.

**Bulk pause.** Loop [subscriptionsPauseCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsPauseCreate) across the list, passing the same `pause_until` date for the cohort, a per-row `pause_until` from your input file, or `{}` for indefinite pauses.

```json title="__http:POST:https://{store}.29next.store/api/admin/subscriptions/{id}/pause/"
{
    "pause_until": "2026-08-01"
}
```

> **Warning:** Do not bulk pause by PATCHing `status: "paused"`. Use the pause endpoint so the platform records the pause lifecycle fields and applies pause behavior consistently.

**Bulk renewal-date shift.** Update each subscription's `next_renewal_date` to defer or align upcoming charges across a cohort.

```json title="__http:PATCH:https://{store}.29next.store/api/admin/subscriptions/{id}/"
{
    "next_renewal_date": "2026-08-17T10:09:01-04:00"
}
```

> **Note:** When computing the new date, preserve the store-local timezone offset returned by the API (e.g., `-04:00`). The platform evaluates renewals in store-local time, so avoid converting to UTC.

**Bulk cancellation.** Loop [subscriptionsCancelCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsCancelCreate) across the list, passing the same `cancel_reason` for the cohort. Suppress the customer email with `send_cancel_notification: false` if you're handling communications separately.

**Bulk gateway migration.** When a gateway is being retired, iterate PATCH calls that update `payment_details.gateway.id` on each affected bankcard subscription.


# Fulfillment Service Apps (https://developers.nextcommerce.com/docs/apps/guides/fulfillment-service)

Fulfillment service apps are integrations that manage fulfillment of physical products for merchants by enabling transparent communication between fulfillment providers and merchants using the Next Commerce dashboard.

> **Note:** View a fully functional [Demo Fulfillment Service App](https://github.com/NextCommerceCo/demo-fulfillment-service-app) to see all of the concepts in action with detailed code examples.

## Fulfillment Flow Overview [#fulfillment-flow-overview]

Below is a high-level overview of the fulfillment flow for fulfillment services to accept and process assigned fulfillment orders.

```mermaid
sequenceDiagram
  autonumber
  Customer->>Store: New Order Created
  Store->>Fulfillment Service App: Creates a Fulfillment Request
  Fulfillment Service App->>Store: Retrieves Assigned Fulfillment Orders
  Fulfillment Service App->>Store: Accepts Fulfillment Request
  Fulfillment Service App->>Carrier: Processes Fulfillment Order with Carrier
  Fulfillment Service App->>Store: Creates a Fulfillment
  Carrier->>Customer: Carrier Delivers Ordered Products to Customer
```

### Fulfillment Flow Detail [#fulfillment-flow-detail]

### Step 1 - New Order Created [#step-1---new-order-created]

All orders start with a customer creating a new order in the Checkout Flow, Admin API, or a recurring Subscription. Orders contain multiple [Fulfillment Orders](#fulfillment-orders), each with the products allocated to the same [Fulfillment Location](#fulfillment-locations) that has the products in stock.

### Step 2 - Store Creates a Fulfillment Request [#step-2---store-creates-a-fulfillment-request]

After a delay period (usually several hours), the store will send a fulfillment request to the [Fulfillment Location](#fulfillment-locations) assigned to the order. Fulfillment Requests can be initiated by dashboard users, background processes, or via the Admin API. See [Fulfillment Locations](#fulfillment-locations).

### Step 3 - Fulfillment Service Retrieves Assigned Fulfillment Orders [#step-3---fulfillment-service-retrieves-assigned-fulfillment-orders]

In response to receiving a fulfillment request, the fulfillment service needs to retrieve all of their assigned fulfillment orders from the [Assigned Fulfillment Orders](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/assignedFulfillmentOrdersList) API endpoint. See [Assigned Fulfillment Orders](#assigned-fulfillment-orders).

### Step 4 - Fulfillment Service Accepts Fulfillment Request [#step-4---fulfillment-service-accepts-fulfillment-request]

For each assigned fulfillment order request in Step 3, the fulfillment service needs to `Accept` or `Reject` the assignment to notify the store the order is expected to be fulfilled or not. See [Accepting Fulfillment Requests](#accepting-fulfillment-requests).

### Step 5 - Fulfillment Service Processes Fulfillment Order with Carrier [#step-5---fulfillment-service-processes-fulfillment-order-with-carrier]

Accepted fulfillment orders are processed by the fulfillment service location to prepare shipment to the customer.

### Step 6 - Fulfillment Service Creates a Fulfillment [#step-6---fulfillment-service-creates-a-fulfillment]

Once an order has been fulfilled, the fulfillment service creates a fulfillment to upload with shipment carrier tracking information and notify the customer their order has shipped. See [Creating Fulfillments](#creating-fulfillments).

### Step 7 - Carrier Delivers Ordered Products to Customer [#step-7---carrier-delivers-ordered-products-to-customer]

The carrier is responsible for delivering the products to the customer in this stage.

## Fulfillment Orders [#fulfillment-orders]

A Fulfillment Order represents items in an order that are to be fulfilled from the same location. A single order often contains multiple fulfillment orders, it's important to keep this in mind for your integration.

```mermaid
graph
  Order-->FO1[Fulfillment Order 1<br>Location A]
  Order-->FO2[Fulfillment Order 2<br>Location B]
  FO1-->P1[Product X Qty 1]
  FO2-->P2[Product Y Qty 1 <br> Product Z Qty 2]
```

## Fulfillment Locations [#fulfillment-locations]

Fulfillment Services need to create `Locations` which represent their warehouses where physical products are stored and fulfilled from. Product `stockrecords` must be associated with a location for fulfillment.

When new orders are created, the fulfillment orders are assigned to the locations based on [Fulfillment Routing](https://docs.nextcommerce.com/docs/features/fulfillment-guide/location-based-routing). The Location Address is also used for Tax calculation. See the [Locations Create](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/locationsCreate) endpoint to create a location.

### Location Callback [#location-callback]

The location `callback` is a URL the store will send `Fulfillment Request` webhooks to notify them of a new fulfillment assigned. Fulfillment Services need to query their [Assigned Fulfillment Orders](#assigned-fulfillment-orders) to retrieve the fulfillment order details.

> **Warning:** Fulfullment Requests are sent to the location `callback` + `/fulfillment-order-notification/`.

**Fulfillment assignment request types are:**

* `fulfillment_requested` - when a new fulfillment order has been requested to be fulfilled.
* `cancellation_requested`- when an already processing fulfillment order has been requested to cancel fulfillment.

  
**Fulfillment Request**

    ```json title="Example Fulfillment Request Payload"
    {
      "type": "fulfillment_requested"
    }
    ```
  

  
**Cancellation Request**

    ```json title="Example Cancellation Request Payload"
    {
      "type": "cancellation_requested"
    }
    ```
  

> **Tip:** The webhook request has a `X-29Next-Store` header that indicates which store the request is from if you have a global callback url.

## Assigned Fulfillment Orders [#assigned-fulfillment-orders]

The [Assigned Fulfillment Orders](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/assignedFulfillmentOrdersList) will return a list of all fulfillment orders assigned to your locations. Your app is recommended to call this API in response to receiving a notification to the location callback, and you may also want to poll this endpoint occasionally (ie once per hour) to ensure you've actioned everything requested.

> **Note:** Use the appropriate `assignment_status` parameter to filter the fulfillment orders to those that require action.

  
**Fulfillment Requests**

    Retrieve all pending Fulfillment Requests

    ```json title="__http:GET:https://{store}.29next.store/api/admin/assigned-fulfillment-orders/?assignment_status=fulfillment_requested"
    {}
    ```
  

  
**Cancellation Requests**

    Retrieve all pending Cancellation Requests

    ```json title="__http:GET:https://{store}.29next.store/api/admin/assigned-fulfillment-orders/?assignment_status=cancellation_requested"
    {}
    ```
  

> **Tip:** Requests to the location callback indicate the request `type` that should be passed to the [Assigned Fulfillment Orders](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/assignedFulfillmentOrdersList) API as the `assignment_status` querystring value to filter fulfillment orders to those for the flow.
> 
>   For example, to see new fulfillment requests pending acceptance, pass `assignment_status=fulfillment_requested` to the Assigned Fulfillment Orders API, `fulfillment_requested` was passed as `type` to the callback.

## Customized Products [#customized-products]

Customized or personalized products carry their customization details in the line item `properties`. When an order is created with line item `properties` (see [Custom Line Item Properties](https://developers.nextcommerce.com/docs/admin-api/guides/external-checkout#custom-line-item-properties)), those values flow through to the fulfillment order line items so your fulfillment service can fulfill the customization.

Each `line_item` returned from the [Assigned Fulfillment Orders](#assigned-fulfillment-orders) API includes a `properties` object with the customization details to fulfill.

```json title="Fulfillment Order Line Item Properties"
"line_items": [
    {
        "product_title": "Engraved Bottle",
        "sku": "BOTTLE-001",
        "quantity": 1,
        "properties": {
            "engraving": "Best Dad Ever",
            "font": "Serif",
            "gift_message": "Happy Birthday!"
        }
    }
]
```

> **Note:** Line item `properties` also determine the uniqueness of line item products — identical products with different `properties` are kept as separate line items.

## Accepting Fulfillment Requests [#accepting-fulfillment-requests]

To `Accept` a Fulfillment Request assignment, send a POST request to the [Fulfillment Request Accept](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentRequestAccept) Endpoint. The Fulfillment Order will show as **Accepted** in the dashboard and the Order will transition fulfillment\_status to processing.

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/fulfillment-request/accept/"
{}
```

## Rejecting Fulfillment Requests [#rejecting-fulfillment-requests]

Your fulfillment service can `Reject` fulfillment order assignments which will prompt the merchant to take action in their store to amend the order. Rejecting fulfillment requests can be for many reasons, such as incorrectly assigned for unavailable products, no stock available, or invalid address. The Fulfillment Service should verify the order details before accepting, by rejecting the fulillment request it will prompt the merchant to correct the order and then send an updated fulfillment request. See possible rejection reasons on in the [Fulfillment Request Reject API docs](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentRequestReject).

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/fulfillment-request/reject/"
{
    "rejected_reason": "incorrect_address",
    "message": "Your Message"
}
```

## Cancellation Flow Overview [#cancellation-flow-overview]

It is common for customers to contact merchants after orders have already been sent to fulfillment service partners for processing. Merchants have the ability to "Request Fulfillment Cancellation" which will send a `cancellation_request` to your [Location Callback](#location-callback). Fulfillment Services are expected to respond to these requests.

```mermaid
sequenceDiagram
  autonumber
  Store->>Fulfillment Service App: Creates a Cancellation Request
  Fulfillment Service App->>Store: Retrieves Cancellation Requests
  Fulfillment Service App->>Store: Accept/Reject Cancellation Requests
```

### Cancellation Flow Detail [#cancellation-flow-detail]

### Step 1 - Store Creates Cancellation Request [#step-1---store-creates-cancellation-request]

Merchants will trigger a cancellation request which will send a cancellation request to the [Fulfillment Location](#fulfillment-locations) assigned to the order.

### Step 2 - Fulfillment Service Retrieves Cancellation Requests [#step-2---fulfillment-service-retrieves-cancellation-requests]

In response to receiving a cancellation request, the fulfillment service needs to retrieve all of its assigned cancellation requests from the [Assigned Fulfillment Orders](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/assignedFulfillmentOrdersList) API endpoint.

```json title="__http:GET:https://{store}.29next.store/api/admin/assigned-fulfillment-orders/?assignment_status=cancellation_requested"
{}
```

### Step 3 - Fulfillment Service Accepts/Rejects Cancellation Request [#step-3---fulfillment-service-acceptsrejects-cancellation-request]

At this stage, the Fulfillment Service needs to [Accept](#accepting-cancellation-requests) or [Reject](#rejecting-cancellation-requests) the cancellation request to respond to the merchant's request.

## Accepting Cancellation Requests [#accepting-cancellation-requests]

To `accept` the cancellation request, send a request to the [Cancellation Request Accept API](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/cancellationRequestAccept).

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/cancellation-request/accept/"
{}
```

## Rejecting Cancellation Requests [#rejecting-cancellation-requests]

If an fulfillment order is too far along in fulfillment processing, fulfillment service partners can reject cancellation requests.

To `reject` a cancellation request, send a request to the [Cancellation Request Reject API](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/cancellationRequestReject). If you include a message, it will show in the order timeline events for the merchant to see.

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/cancellation-request/reject/"
{
    "message": "Order already shipped."
}
```

## Creating Fulfillments [#creating-fulfillments]

Once you have tracking information for your the outgoing shipment to the customer, create a Fulfillment for the fulfillment order on the [Fulfillments Create](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentsCreate) API.

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/fulfillments/"
{
  "notify": true, // send the customer an order shipped notification email
  "tracking_info": [
    {
      "tracking_code": "EXAMPLECODE",
      "carrier": "dhl_ecommerce"
    }
  ]
}
```

## Partial Fulfillments [#partial-fulfillments]

Sometimes a fulfillment order can't be shipped in a single shipment — for example when items are backordered, or part of the order is ready early. The [Fulfillments Create](https://developers.nextcommerce.com/docs/admin-api/reference/fulfillment/fulfillmentsCreate) endpoint supports partial fulfillments by accepting the optional `fulfillment_order_line_items` array. Pass only the line items (and quantities) you are ready to ship in this call, and the remaining items stay on the original fulfillment order for a later fulfillment.

### Behavior [#behavior]

* The fulfilled line items are moved from the current fulfillment order into a new closed fulfillment order.
* The remaining items stay on the original fulfillment order, which stays open waiting to be fulfilled.

### Example Partial Fulfillment Request [#example-partial-fulfillment-request]

The example below fulfills 1 of 2 units of `line_item` `101` and leaves the other unit — along with all of `line_item` `102` — on the original fulfillment order.

```json title="__http:POST:https://{store}.29next.store/api/admin/fulfillment-orders/{id}/fulfillments/"
{
  "notify": true,
  "fulfillment_order_line_items": [
    {
      "id": 101,
      "quantity": 1
    }
  ],
  "tracking_info": [
    {
      "tracking_code": "EXAMPLECODE",
      "carrier": "dhl_ecommerce"
    }
  ]
}
```

> **Note:** Omit `fulfillment_order_line_items` (as in the standard [Creating Fulfillments](#creating-fulfillments) example) to fulfill every remaining item on the fulfillment order in one call.

## Sync Product Inventory [#sync-product-inventory]

Products have "stock records" which represent the available physical stock at a fulfillment location. Often a single product can be stocked at multiple locations, with [Fulfillment Routing](https://docs.nextcommerce.com/docs/features/fulfillment-guide/location-based-routing) governing the order fulfillment location assignment.

```mermaid
flowchart TD
    B(&#x22;Product / SKU&#x22;)
    B-->C(&#x22;Location 1&#x22;)
    B-->D(&#x22;Location 2&#x22;)
    B-->E(&#x22;Location 3&#x22;)
```

### Retrieve Stock Records by Location [#retrieve-stock-records-by-location]

Fulfillment services can retrieve all stock records from a store to map with the SKUs at their warehouse. You can also search and filter by product name or SKU, see Admin API docs for [stockrecordsRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/products/stockrecordsRetrieve).

```json title="__http:GET:https://{store}.29next.store/api/admin/stockrecords/?location_id={id}"
{}
```

With the list of stock records assigned to your location, you can now update the `num_in_stock` to reflect the current available units.

### Update Number of Units In Stock [#update-number-of-units-in-stock]

Fulfillment services are recommended to update the number in stock (`num_in_stock`) at regular intervals so that the store inventory is update to date and accurate.

```json title="__http:PATCH:https://{store}.29next.store/api/admin/stockrecords/{id}/"
{
  "num_in_stock": 1000
}
```

## Moving Fulfillment Orders [#moving-fulfillment-orders]