Ankorstore OrderPay API

ℹ️ This section describes the API endpoints for managing _OrderPay_ orders and customers. OrderPay allows brands to create and manage orders for their own customers, handle payments, and track order lifecycle — all through the Ankorstore platform. ## 💡 General Concepts - _OrderPay Order_ - An order created by a brand on behalf of one of its customers. Unlike _Internal Orders_ (placed by retailers on the Ankorstore marketplace), OrderPay orders are initiated by the brand itself. This enables brands to sell to customers outside the marketplace while still leveraging Ankorstore's payment processing, invoicing, and optionally, fulfillment services. - _OrderPay Customer_ - A customer entity managed by the brand. Each customer has billing and shipping addresses, contact details, and associated payment methods. Customers must be created before orders can be placed for them. - _Custom Items_ - Additional charges on an order beyond product line items, such as shipping fees, excise duties, or eco-taxes. ## 💡 Working with Customers Before creating an order, you need to register the customer. Use the customer endpoints to create and manage your customer base. ### Creating a Customer A customer requires at minimum: store name, email, first/last name, phone number, and both billing and shipping addresses. ```json5 // POST /api/v1/order-pay/order-pay-customer { "data": { "type": "order-pay-customer", "attributes": { "storeName": "La Boutique Verte", "email": "contact@laboutiqueverte.fr", "firstName": "Marie", "lastName": "Dupont", "company": { "phoneNumber": "+33612345678", "vatNumber": "FR12345678901", "vatExemption": false }, "billingAddress": { "street": "12 Rue de la Paix", "postalCode": "75002", "city": "Paris", "countryCode": "FR" }, "shippingAddress": { "street": "12 Rue de la Paix", "postalCode": "75002", "city": "Paris", "countryCode": "FR" } } } } ``` ### Listing and Filtering Customers You can retrieve your customers with optional filters: ``` [GET] /api/v1/order-pay/order-pay-customer?filter[storeName]=boutique&sort=storeName ``` The response uses page-based pagination with `page[number]` and `page[size]` parameters. ### Including Payment Methods When retrieving a single customer, pass `?include=paymentMethods` to see the customer's stored payment methods. ## 💡 Working with Orders ### Order Lifecycle An OrderPay order goes through the following statuses: stateDiagram-v2 [*] --> created created --> brand_confirmed : Brand confirms created --> cancelled : Brand cancels brand_confirmed --> payment_confirmed : Payment processed brand_confirmed --> cancelled : Brand cancels payment_confirmed --> waiting_shipping waiting_shipping --> shipped shipped --> received received --> invoiced invoiced --> brand_paid brand_paid --> [*] cancelled --> [*] | Status | Description | | --- | --- | | `created` | Order has been created but not yet confirmed by the brand | | `brand_confirmed` | Brand has confirmed the order, payment will be processed | | `payment_confirmed` | Payment has been successfully processed | | `waiting_shipping` | Order is awaiting shipment | | `shipped` | Order has been shipped | | `received` | Customer has received the order | | `invoiced` | Invoice has been generated | | `brand_paid` | Brand has been paid for the order | | `cancelled` | Order has been cancelled | ### Creating an Order To create an order you need the customer UUID and at least one product line item. Each item requires a `productVariantUuid`, a `quantity` (in packs), and pricing in the brand's currency. > ⚠️ The `quantity` field represents the number of **packs**, not individual units. For example, if a product variant is > sold in packs of 6, a quantity of 2 means 12 individual units. ```json5 // POST /api/v1/order-pay/order-pay-orders { "data": { "type": "order-pay-orders", "attributes": { "customerUuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "customReference": "SHOP-12345", // Your reference, shown on customer invoice "items": [ { "productVariantUuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "quantity": 2, "amounts": { "brandUnitPrice": 1500, // 15.00 EUR in cents "discountRate": 10 // 10% discount } } ], "customItems": [ { "type": "shippingFees", "amount": 800 // 8.00 EUR in cents, excl. VAT } ], "shippingMethod": "custom" // "custom" or "fulfillment" } } } ``` ### Shipping Methods | Method | Description | | --- | --- | | `custom` | You ship the order using your own carrier | | `fulfillment` | The order is fulfilled via AnkorLogistics Fulfillment Centre | When using `fulfillment`, you can optionally provide delivery instructions: - `deliverySchedule` - Customer opening times with day-of-week and time slots - `packingInstruction` - Services like `PALLETISE`, `CUSTOM_BUILD`, or `DOCS` - `deliveryAppointment` - Whether an appointment is required for delivery ### Custom Items Use `customItems` to add charges beyond product line items: | Type | Description | | --- | --- | | `shippingFees` | Shipping charges | | `exciseDuties` | Excise duties (e.g., on alcohol) | | `ecoTax` | Environmental taxes | > ⚠️ The `amounts.shippingFeesAmount` field is **deprecated**. Use `customItems` with type `shippingFees` instead. ### Custom Reference Use the `customReference` field to link orders back to your own system (e.g., a Shopify order ID). This reference appears on the customer's invoice and can be up to 64 characters. ### Confirming and Cancelling Orders After creating an order, you can: - **Confirm** it via `POST /api/v1/order-pay/order-pay-orders/{id}/-actions/confirm` — this triggers payment processing - **Cancel** it via `POST /api/v1/order-pay/order-pay-orders/{id}/-actions/cancel` — with an optional reason ### Including Payment Details When retrieving an order, pass `?include=payment` or `?include=payment.transactions` to see payment status and transaction details. ## 💡 Amounts and Currencies All monetary amounts are represented as **integers in the lowest denomination** of the currency (e.g., cents for EUR). Every order response includes both brand-currency and customer-currency amounts, with formatted string equivalents for display purposes. For example, a line item response includes fields like: - `brandUnitPrice`: `1500` (integer, cents) - `brandUnitPriceFormatted`: `"15.00 EUR"` (string, for display) - `customerUnitPrice`: `1320` (integer, cents in customer currency) - `customerUnitPriceFormatted`: `"13.20 GBP"` (string, for display) VAT is calculated automatically based on the customer's address and product configuration.