Skip to content

Create Merchant Order ​

Use this endpoint to create an order programmatically on behalf of a customer. You can specify whether to generate an online payment link or mark the order for offline payment collection.

Endpoint ​

POST /v1/orders

Authentication ​

  • Requires merchant authentication: Authorization: Bearer JWT_TOKEN.
  • Requires X-MerchantApiKey: MERCHANT_API_KEY.

Headers ​

json
{
  "Authorization": "Bearer JWT_TOKEN",
  "X-MerchantApiKey": "MERCHANT_API_KEY",
  "Content-Type": "application/json"
}

Request body ​

Field NameTypeRequiredDescription
firstNamestringYesCustomer's first name.
lastNamestringYesCustomer's last name.
emailstringYesCustomer's email address.
phoneNumberstringYesCustomer's telephone number.
shippingAddressstringYesDelivery street address.
citystringYesDestination city.
statestringYesDestination state.
countrystringNoDestination country.
shippingFeenumberNoDelivery fee amount. Default: 0.
shippingMethodstringNoSelected delivery method (e.g. Standard Delivery).
promoCodestringNoOptional discount or promotion code.
paymentActionstringYesPayment mode: GENERATE_PAYMENT_LINK or COLLECT_OFFLINE.
paymentGatewaystringNoPayment gateway (PAYSTACK, STRIPE, OFFLINE). Default: PAYSTACK.
callbackUrlstringNoRedirect URL after customer completes payment.
itemsarrayYesList of ordered products.
items[].productIdstringYesUnique identifier of the product.
items[].variantGroupIdstringNoVariant group ID for V2 products.
items[].skuIdstringNoSKU ID for variable product items.
items[].quantityintegerYesQuantity to order (minimum 1).
json
{
  "firstName": "Ade",
  "lastName": "Johnson",
  "email": "ade.johnson@example.com",
  "phoneNumber": "+2348023456789",
  "shippingAddress": "15 Admiralty Way, Lekki Phase 1",
  "city": "Lekki",
  "state": "Lagos",
  "country": "Nigeria",
  "shippingFee": 2000.00,
  "shippingMethod": "Express Courier",
  "paymentAction": "GENERATE_PAYMENT_LINK",
  "paymentGateway": "PAYSTACK",
  "callbackUrl": "https://mystore.com/orders/success",
  "items": [
    {
      "productId": "679f8f5a3b5f2173201c2582",
      "skuId": "679f8f5a3b5f2173201c2583",
      "quantity": 1
    }
  ]
}

Responses ​

200 OK ​

json
{
  "status": true,
  "message": "Order created successfully",
  "data": {
    "order": {
      "id": "67d3412df1f14227873214f4",
      "orderNumber": "ORD-841EBF47",
      "orderDate": "2026-03-08T12:00:00Z",
      "totalPrice": "14500.00",
      "status": "PENDING",
      "paymentStatus": "PENDING",
      "fulfillmentStatus": "UNFULFILLED"
    },
    "paymentLink": {
      "url": "https://paystack.com/pay/abc-123",
      "reference": "ref_841EBF47_1741432000",
      "expiresAt": "2026-03-09T12:00:00Z"
    }
  }
}

Build with joy