Ankorstore OrderPay API

ℹ️ This section describes the API endpoints for managing _OrderPay_ orders and customers. OrderPay allows brandsto create and manage orders for their own customers, handle payments, and track order lifecycle — all through theAnkorstore 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 beplaced for them. - _Custom Items_ - Additional charges on an order beyond product line items, such as shipping fees, excise duties, or eco-taxes.## 💡 Working with CustomersBefore creating an order, you need to register the customer. Use the customer endpoints to create and manage yourcustomer base.### Creating a CustomerA customer requires at minimum: store name, email, first/last name, phone number, and both billing and shippingaddresses.```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 CustomersYou 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 MethodsWhen retrieving a single customer, pass `?include=paymentMethods` to see the customer's stored payment methods.## 💡 Working with Orders### Order LifecycleAn 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 OrderTo 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 ItemsUse `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 ReferenceUse the `customReference` field to link orders back to your own system (e.g., a Shopify order ID). This referenceappears on the customer's invoice and can be up to 64 characters.### Confirming and Cancelling OrdersAfter 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 DetailsWhen retrieving an order, pass `?include=payment` or `?include=payment.transactions` to see payment status andtransaction details.## 💡 Amounts and CurrenciesAll 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 equivalentsfor 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.