Statuses

Order Status Management

The Statuses API allows you to manage order statuses in your store. You can retrieve, create, update, and delete custom order statuses to match your business workflow.

GET /api/statuses/

Retrieve a list of all order statuses in your store. This endpoint supports pagination.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`items_per_page`	integer	No	Number of items per page (default: 10)
`type`	string	No	Filter by status type (e.g., "O" for order statuses)

Example Response

{
  "statuses": [
    {
      "status_id": "1",
      "status": "O",
      "description": "Open",
      "email_subj": "Your order has been placed",
      "email_header": "Thank you for your order!",
      "type": "O",
      "is_default": "Y"
    },
    {
      "status_id": "2",
      "status": "P",
      "description": "Processed",
      "email_subj": "Your order has been processed",
      "email_header": "We're processing your order",
      "type": "O",
      "is_default": "N"
    },
    {
      "status_id": "3",
      "status": "C",
      "description": "Complete",
      "email_subj": "Your order has been completed",
      "email_header": "Your order is complete",
      "type": "O",
      "is_default": "N"
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 3
  }
}

GET /api/statuses/{status_id}/

Retrieve details for a specific status by its ID.

Example Response

{
  "status_id": "1",
  "status": "O",
  "description": "Open",
  "email_subj": "Your order has been placed",
  "email_header": "Thank you for your order!",
  "email_body": "Dear [customer],\n\nThank you for placing an order in our store. We will notify you when your order ships.",
  "type": "O",
  "is_default": "Y",
  "params_by_lang": {
    "en": {
      "description": "Open",
      "email_subj": "Your order has been placed",
      "email_header": "Thank you for your order!",
      "email_body": "Dear [customer],\n\nThank you for placing an order in our store. We will notify you when your order ships."
    },
    "es": {
      "description": "Abierto",
      "email_subj": "Su pedido ha sido realizado",
      "email_header": "¡Gracias por su pedido!",
      "email_body": "Estimado [customer],\n\nGracias por realizar un pedido en nuestra tienda. Le notificaremos cuando su pedido sea enviado."
    }
  }
}

POST /api/statuses/

Create a new custom order status.

Request Parameters

Parameter	Type	Required	Description
`status`	string	Yes	Status code (single letter)
`description`	string	Yes	Status description
`email_subj`	string	No	Email subject line
`email_header`	string	No	Email header text
`email_body`	string	No	Email body text
`type`	string	Yes	Status type (e.g., "O" for order)
`is_default`	string	No	"Y" or "N" (default: "N")
`params_by_lang`	object	No	Localized status parameters

Example Request

{
  "status": "S",
  "description": "Shipped",
  "email_subj": "Your order has been shipped",
  "email_header": "Your order is on its way!",
  "email_body": "Dear [customer],\n\nYour order has been shipped and is on its way to you. You can track your shipment using the tracking number below.",
  "type": "O",
  "is_default": "N",
  "params_by_lang": {
    "en": {
      "description": "Shipped",
      "email_subj": "Your order has been shipped",
      "email_header": "Your order is on its way!",
      "email_body": "Dear [customer],\n\nYour order has been shipped and is on its way to you. You can track your shipment using the tracking number below."
    },
    "es": {
      "description": "Enviado",
      "email_subj": "Su pedido ha sido enviado",
      "email_header": "¡Su pedido está en camino!",
      "email_body": "Estimado [customer],\n\nSu pedido ha sido enviado y está en camino. Puede realizar el seguimiento de su envío utilizando el número de seguimiento a continuación."
    }
  }
}

Email Variables: You can use the following variables in email templates:

[customer] - Customer's name
[order_id] - Order ID
[shipping_method] - Shipping method name
[tracking_number] - Shipment tracking number

PUT /api/statuses/{status_id}/

Update an existing order status.

Example Request

{
  "description": "Order Completed",
  "email_header": "Your order is now complete!",
  "email_body": "Dear [customer],\n\nThank you for shopping with us. Your order has been completed and we hope you're satisfied with your purchase."
}

Note: When updating a status, you only need to include the fields you want to change. Other fields will retain their current values.

DELETE /api/statuses/{status_id}/

Delete a custom order status.

Important: You cannot delete system default statuses or statuses that are currently in use by orders. Make sure no orders are using the status before attempting to delete it.

Default Order Statuses

Code	Description
`O`	Open (Initial status when an order is created)
`P`	Processed (Order has been processed)
`C`	Complete (Order has been completed)
`F`	Failed (Order processing has failed)
`D`	Declined (Order has been declined)
`B`	Backordered (Items in order are backordered)
`I`	Cancelled (Order has been cancelled)

Tip: When creating custom order statuses, choose single-letter codes that are not already used by the default statuses to avoid confusion.