Skip to main content
PUT
/
api
/
v1
/
i
/
orders
/
{id}
curl -X PUT "https://api.example.com/api/v1/i/orders/a3d5c8e7-9b4f-4a2e-8c7d-1f3e5a6b9c0d/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "street_address": "456 Oak Avenue",
      "postal_code": 67890,
      "city": "Springfield",
      "state": "IL",
      "country": "United States"
    }
  }'

{
  "id": "a3d5c8e7-9b4f-4a2e-8c7d-1f3e5a6b9c0d",
  "url": "https://api.example.com/api/v1/i/orders/a3d5c8e7-9b4f-4a2e-8c7d-1f3e5a6b9c0d/",
  "customer": {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "created": "2026-03-01T10:30:00Z",
  "updated": "2026-03-01T11:45:00Z",
  "billing_address": {
    "street_address": "456 Oak Avenue",
    "postal_code": 67890,
    "city": "Springfield",
    "state": "IL",
    "country": "United States"
  },
  "items": [
    {
      "id": 1,
      "product": {
        "id": 42,
        "name": "Wireless Headphones",
        "slug": "wireless-headphones"
      },
      "variant": 101,
      "unit_price": "79.99",
      "quantity": 2,
      "shipping": "5.00",
      "discount_amount": "10.00",
      "total_price": "159.98",
      "offer": 5
    }
  ],
  "items_count": 2,
  "savings_on_items": "10.00",
  "status": "awaiting_payment",
  "subtotal": "159.98",
  "amount_saved": "10.00",
  "shipping": "5.00",
  "total_amount": "154.98"
}

​
Description

Updates an existing order’s billing address. Only orders with status awaiting_payment can be modified.

​
Authentication

Requires authentication. The order must belong to the authenticated customer.

​
Path Parameters

​
id
uuid
required
The unique identifier of the order to update

​
Request Body

​
address
object
required
New billing address for the order

​
Response

Returns the updated order object with the same structure as the Get Order endpoint.
​
id
uuid
Order identifier
​
billing_address
object
Updated billing address
​
status
string
Order status (will be awaiting_payment)
​
...
various
All other order fields (see Get Order response)
curl -X PUT "https://api.example.com/api/v1/i/orders/a3d5c8e7-9b4f-4a2e-8c7d-1f3e5a6b9c0d/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "street_address": "456 Oak Avenue",
      "postal_code": 67890,
      "city": "Springfield",
      "state": "IL",
      "country": "United States"
    }
  }'

{
  "id": "a3d5c8e7-9b4f-4a2e-8c7d-1f3e5a6b9c0d",
  "url": "https://api.example.com/api/v1/i/orders/a3d5c8e7-9b4f-4a2e-8c7d-1f3e5a6b9c0d/",
  "customer": {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "created": "2026-03-01T10:30:00Z",
  "updated": "2026-03-01T11:45:00Z",
  "billing_address": {
    "street_address": "456 Oak Avenue",
    "postal_code": 67890,
    "city": "Springfield",
    "state": "IL",
    "country": "United States"
  },
  "items": [
    {
      "id": 1,
      "product": {
        "id": 42,
        "name": "Wireless Headphones",
        "slug": "wireless-headphones"
      },
      "variant": 101,
      "unit_price": "79.99",
      "quantity": 2,
      "shipping": "5.00",
      "discount_amount": "10.00",
      "total_price": "159.98",
      "offer": 5
    }
  ],
  "items_count": 2,
  "savings_on_items": "10.00",
  "status": "awaiting_payment",
  "subtotal": "159.98",
  "amount_saved": "10.00",
  "shipping": "5.00",
  "total_amount": "154.98"
}

​
Modification Restrictions

Only Pending Orders Can Be UpdatedOrders can only be modified when their status is awaiting_payment. Once an order is paid, delivered, or cancelled, the billing address cannot be changed.
Status-based restrictions:
  • awaiting_payment - Can be updated
  • paid - Cannot be updated (returns 403)
  • delivered - Cannot be updated (returns 403)
  • cancelled - Cannot be updated (returns 403)

​
Address Handling

When updating the billing address:
1

Address Validation

The provided address is validated according to the Address model rules.
2

Address Lookup

The system checks if an identical address already exists in the database.
3

Address Assignment

  • If address exists: Uses the existing Address record
  • If new: Creates a new Address record
4

Order Update

The order’s billing_address field is updated to reference the address.

​
Field Constraints

​
street_address
string
Maximum length: 30 characters
​
postal_code
integer
Must be a valid positive integer
​
city
string
Maximum length: 50 characters
​
state
string
Maximum length: 50 characters
​
country
string
Maximum length: 30 characters. Must be full name (more than 3 characters).

​
Notes

  • Only the billing address can be updated; order items cannot be modified after creation
  • To modify items, the order must be deleted and recreated from the cart
  • The updated timestamp is automatically set to the current time
  • Address validation ensures country names are full names, not abbreviations
  • If multiple identical addresses exist, the first one found is used

Build docs developers (and LLMs) love

Get started for freeTalk to us