Order

A collection of endpoints for creating and managing orders

Copy link List Orders

List the previously created orders

Query Parameters

perPageinteger
Number of records to fetch per page
pageinteger
The section to retrieve
fromstring
The start date
tostring
The end date

Response

200Order List response
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
6 object properties
totalrequiredinteger
revenuerequiredobject
skippedrequiredinteger
perPagerequiredinteger
pagerequiredinteger
pageCountrequiredinteger
GET/order
curl https://api.paystack.co/order \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.order.list({
  perPage: 100,
  page: 100
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.order.list({
  per_page: 100,
  page: 100
})
puts response.data
Response
{
  "status": true,
  "message": "Orders retrieved",
  "data": [
    {
      "id": 12345,
      "code": "ORD_abc123def456",
      "amount": 20000,
      "currency": "NGN",
      "status": "success",
      "customer": {
        "email": "[email protected]"
      },
      "createdAt": "2024-11-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Create Order

Create an order for selected items

Request Body

emailrequiredstring
The email of the customer placing the order
first_namerequiredstring
The customer's first name
last_namerequiredstring
The customer's last name
phonerequiredstring
The customer's mobile number
currencyrequiredstring
Currency in which amount is set
EnumGHSKESNGNUSDZAR
itemsrequiredarray[object]
shippingrequiredobject
The shipping details of the order
6 object properties
street_linerequiredstring
The address of for the delivery
cityrequiredstring
The city of the delivery address
staterequiredstring
The state of the delivery address
countryrequiredstring
The country of the delivery address
shipping_feerequiredinteger
The cost of delivery
delivery_notestring
Extra details to be aware of for the delivery
is_giftboolean
A flag to indicate if the order is for someone else
pay_for_meboolean
A flag to indicate if the someone else should pay for the order

Response

200Order Create response
statusrequiredboolean
messagerequiredstring
datarequiredobject
24 object properties
discountsrequiredarray[object]
currencyrequiredstring
shipping_addressrequiredstring
integrationrequiredinteger
domainrequiredstring
emailrequiredstring
customerrequiredinteger
amountrequiredinteger
pay_for_merequiredboolean
shippingrequiredobject
14 object properties
customerrequiredinteger
integrationrequiredinteger
domainrequiredstring
feesrequiredinteger
delivery_noterequiredstring
street_linerequiredstring
cityrequiredstring
staterequiredstring
countryrequiredstring
is_shippedrequiredboolean
delivery_tracking_linkrequiredstring
idrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
shipping_feesrequiredinteger
shipping_methodobject
3 object properties
regionrequiredstring
feerequiredinteger
currencyrequiredstring
metadatarequiredobject
order_coderequiredstring
statusrequiredstring
refundedrequiredboolean
is_viewedrequiredboolean
expiration_daterequiredstring
idrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
itemsrequiredarray[object]
pay_for_me_coderequiredstring
discount_amountrequiredinteger
POST/order
curl https://api.paystack.co/order \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+2348123456789",
    "currency": "GHS",
    "items": [],
    "shipping": {}
  }' \
  -X POST
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.order.create({
  email: "[email protected]",
  first_name: "Jane",
  last_name: "Doe",
  phone: "+2348123456789",
  currency: "GHS",
  items: [],
  shipping: {}
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.order.create({
  email: "[email protected]",
  first_name: "Jane",
  last_name: "Doe",
  phone: "+2348123456789",
  currency: "GHS",
  items: [],
  shipping: {}
})
puts response.data
Response
{
  "status": true,
  "message": "Order created",
  "data": {
    "id": 12345,
    "code": "ORD_abc123def456",
    "amount": 20000,
    "currency": "NGN",
    "status": "pending",
    "customer": {
      "id": 297346561,
      "email": "[email protected]"
    },
    "line_items": [
      {
        "product": {
          "id": 2196244,
          "name": "Sample Product"
        },
        "quantity": 2,
        "amount": 20000
      }
    ],
    "createdAt": "2024-11-01T12:00:00.000Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Fetch Order

Fetch the details of a previously created order

Path Parameters

idrequiredinteger
The unique identifier of the order

Response

200Order Fetch response
statusrequiredboolean
messagerequiredstring
datarequiredobject
30 object properties
discountsrequiredarray[object]
order_coderequiredstring
domainrequiredstring
currencyrequiredstring
amountrequiredinteger
emailrequiredstring
statusrequiredstring
refundedrequiredboolean
paid_atrequiredstring
shipping_addressrequiredstring
metadatarequiredobject
shipping_feesrequiredinteger
shipping_methodrequiredstring
is_viewedrequiredboolean
expiration_daterequiredstring
pay_for_merequiredboolean
idrequiredinteger
integrationrequiredinteger
pagerequiredstring
customerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredobject
risk_actionrequiredstring
international_format_phonerequiredstring
shippingrequiredstring
createdAtrequiredstring
updatedAtrequiredstring
transactionrequiredinteger
is_giftrequiredboolean
payerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredobject
risk_actionrequiredstring
international_format_phonerequiredstring
fully_refundedrequiredboolean
refunded_amountrequiredinteger
itemsrequiredarray[object]
discount_amountrequiredstring
GET/order/{id}
curl https://api.paystack.co/order/1559046 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.order.fetch("1559046");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.order.fetch("1559046")
puts response.data
Response
{
  "status": true,
  "message": "Order retrieved",
  "data": {
    "id": 12345,
    "code": "ORD_abc123def456",
    "amount": 20000,
    "currency": "NGN",
    "status": "success",
    "customer": {
      "id": 297346561,
      "email": "[email protected]"
    },
    "line_items": [
      {
        "product": {
          "id": 2196244,
          "name": "Sample Product"
        },
        "quantity": 2,
        "amount": 20000
      }
    ],
    "createdAt": "2024-11-01T12:00:00.000Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Fetch Product Orders

Fetch all orders for a particular product

Path Parameters

idrequiredinteger
The unique identifier of the order

Response

200Order Fetch Product response
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
6 object properties
quantity_soldrequiredinteger
revenuerequiredinteger
totalrequiredinteger
skippedrequiredinteger
perPagerequiredinteger
pageCountrequiredinteger
GET/order/product/{id}
curl https://api.paystack.co/order/product/1559046 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.order.product("1559046");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.order.product("1559046")
puts response.data
Response
{
  "status": true,
  "message": "Product orders retrieved",
  "data": [
    {
      "id": 12345,
      "code": "ORD_abc123def456",
      "amount": 20000,
      "currency": "NGN",
      "status": "success",
      "customer": {
        "email": "[email protected]"
      },
      "createdAt": "2024-11-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Validate Order

Validate a pay for me order

Path Parameters

coderequiredstring
The unique code of a previously created order

Response

200Order Validate response
statusrequiredboolean
messagerequiredstring
datarequiredobject
24 object properties
order_coderequiredstring
domainrequiredstring
currencyrequiredstring
amountrequiredinteger
emailrequiredstring
statusrequiredstring
refundedrequiredboolean
paid_atrequiredstring
shipping_addressrequiredstring
metadatarequiredstring
shipping_feesrequiredinteger
shipping_methodrequiredstring
is_viewedrequiredboolean
expiration_daterequiredstring
pay_for_merequiredboolean
idrequiredinteger
integrationrequiredobject
4 object properties
keyrequiredstring
namerequiredstring
logorequiredstring
allowed_currenciesrequiredarray[object]
transactionrequiredstring
pagerequiredstring
customerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredobject
risk_actionrequiredstring
international_format_phonerequiredstring
shippingrequiredstring
createdAtrequiredstring
updatedAtrequiredstring
payerrequiredstring
GET/order/{code}/validate
curl https://api.paystack.co/order/ORD_6z0lqwpmxrm7dsp/validate \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.order.validate("ORD_6z0lqwpmxrm7dsp");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.order.validate("ORD_6z0lqwpmxrm7dsp")
puts response.data
Response
{
  "status": true,
  "message": "Order is valid",
  "data": {
    "id": 12345,
    "code": "ORD_abc123def456",
    "amount": 20000,
    "currency": "NGN",
    "status": "pending",
    "valid": true
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}