Orders/
Orders API/
Update an Order

Update an Order

You can only update custom data, shipping, shipping_address, and status on orders. All other settings in the order object are immutable.

You can update the shipping, shipping_address, and status of an order only if the order is not fulfilled. You can use the refund API to refund an order only if the payment status is paid. Cancelling an order does not automatically refund a payment. You must refund the orders manually.

  • This request is only accessible to client_credentials token users with Seller Admin role.
  • Non client_credentials token users cannot access this endpoint. See Permissions.

PUT Update by ID

https://api.moltin.com/v2/orders/:id

Parameters

Path parameters

NameRequiredTypeDescription
idRequiredstringThe ID of the order you want to update.

Headers

NameRequiredTypeDescription
AuthorizationRequiredstringThe Bearer token required to get access to the API.

Body

NameRequiredTypeDescription
typeRequiredstringorder

Request examples

Curl

curl -X PUT https://api.moltin.com/v2/orders/:id \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $'{
      "data": {
        "type": "order"
        "shipping_address": {
          "first_name": "John"
        }
      }
    }'

JavaScript SDK

const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
    client_secret: "X",
});
const id = "XXXX";
const order = {
    shipping_address: {
        first_name: "John",
    },
};
Moltin.Orders.Update(id, order).then((order) => {
    // Do something
});

Response example

200 OK

{
    "data": {
        "type": "order",
        "id": "369ad4a4-ee67-48b0-x347-t50a6e61d83d",
        "status": "incomplete",
        "payment": "unpaid",
        "shipping": "unfulfilled",
        "customer": {
            "name": "Mr John Doe",
            "email": "johndoe@example.com"
        },
        "shipping_address": {
            "first_name": "James",
            "last_name": "Doe",
            "phone_number": "",
            "company_name": "",
            "line_1": "1234 Disney Drive",
            "line_2": "Disney Resort",
            "city": "Anaheim",
            "county": "Orange",
            "region": "CA",
            "postcode": "92802",
            "country": "US",
            "instructions": ""
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "company_name": "",
            "line_1": "1234 Disney Drive",
            "line_2": "Disney Resort",
            "city": "Anaheim",
            "county": "Orange",
            "region": "CA",
            "postcode": "92802",
            "country": "US"
        },
        "links": {},
        "meta": {
            "display_price": {
                "with_tax": {
                    "amount": 237500,
                    "currency": "USD",
                    "formatted": "$2175.00"
                },
                "without_tax": {
                    "amount": 237500,
                    "currency": "USD",
                    "formatted": "$2175.00"
                }
            },
            "timestamps": {
                "created_at": "2018-04-16T10:11:59.715Z",
                "updated_at": "2018-04-16T10:11:59.715Z"
            }
        },
        "relationships": {
            "items": {
                "data": [
                    {
                        "type": "item",
                        "id": "de9fddf5-011b-4485-abf8-ebb8f53c39ff"
                    }
                ]
            }
        }
    }
}

PUT Cancel an Order by ID

You can cancel an order only if the order is not fulfilled.

https://api.moltin.com/v2/orders/:id

Parameters

Path parameters

NameRequiredTypeDescription
idRequiredstringThe ID of the order you want to cancel.

Headers

NameRequiredTypeDescription
AuthorizationRequiredstringThe Bearer token required to get access to the API.

Body

NameRequiredTypeDescription
typeRequiredstringThe type of the resource. You must use order.
statusRequiredstringThe status of the order. You can only update the status to cancelled.

Request example

curl -X PUT https://api.moltin.com/v2/orders/:id \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $'{
      "data": {
        "type": "order",
        "status": "cancelled"
        }
      }
    }'

Response example

200 OK

{
    "data": {
        "type": "order",
        "id": "50ca1ec7-cb04-45f0-b7a9-3613ef7c23d3",
        "status": "cancelled",
        "payment": "authorized",
        "shipping": "unfulfilled",
        "anonymized": false,
        "customer": {
            "name": "Andy",
            "email": "andy@example.com"
        },
        "shipping_address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "phone_number": "123-456-1111",
            "company_name": "Elasticpath",
            "line_1": "1234 Disney Drive",
            "line_2": "Disney Resort",
            "city": "Anaheim",
            "county": "Orange",
            "region": "CA",
            "postcode": "92802",
            "country": "US",
            "instructions": ""
        },
        "billing_address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "company_name": "Elasticpath",
            "line_1": "1234 Disney Drive",
            "line_2": "Disney Resort",
            "city": "Anaheim",
            "county": "Orange",
            "region": "CA",
            "postcode": "92802",
            "country": "US"
        },
        "links": {},
        "meta": {
            "display_price": {
                "with_tax": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                },
                "without_tax": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                },
                "tax": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "discount": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2022-02-16T00:30:24Z",
                "updated_at": "2022-02-16T00:32:25Z"
            }
        },
        "relationships": {
            "items": {
                "data": [
                    {
                        "type": "item",
                        "id": "df6f9b0c-b4b6-4fbe-b94c-c36bab71f121"
                    }
                ]
            }
        }
    }
}

You cannot cancel a payment using manual gateway. You can only cancel an order. The following error response is returned when you can cancel a payment using manual gateway:

 "errors": [
        {
            "status": 422,
            "title": "Unsupported gateway operation",
            "detail": "Cancellation is not supported for Manual payment gateway"
        }
    ]
}

PUT Fulfill an Order by ID

You can fulfill a paid order only.

https://api.moltin.com/v2/orders/:id

Parameters

Path parameters

NameRequiredTypeDescription
idRequiredstringThe ID of the order that you want to fulfill.

Headers

NameRequiredTypeDescription
AuthorizationRequiredstringThe Bearer token required to get access to the API.

Body

NameRequiredTypeDescription
typeRequiredstringThe type of the resource. You must use order.
shippingRequiredstringThe shipping status of the order. You can only update the shipping status to fulfilled.

Request example

curl -X PUT https://api.moltin.com/v2/orders/:id \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $'{
      "data": {
        "type": "order",
        "shipping": "fulfilled"
        }
      }
    }'

Response example

200 OK

{
    "data": {
        "type": "order",
        "id": "369ad4a4-ee67-48b0-x347-t50a6e61d83d",
        "status": "complete",
        "payment": "paid",
        "shipping": "fulfilled",
        "customer": {
            "name": "Mr John Doe",
            "email": "johndoe@example.com"
        },
        "shipping_address": {
            "first_name": "James",
            "last_name": "Doe",
            "phone_number": "",
            "company_name": "",
            "line_1": "1234 Disney Drive",
            "line_2": "Disney Resort",
            "city": "Anaheim",
            "county": "Orange",
            "region": "CA",
            "postcode": "92802",
            "country": "US",
            "instructions": ""
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "company_name": "",
            "line_1": "1234 Disney Drive",
            "line_2": "Disney Resort",
            "city": "Anaheim",
            "county": "Orange",
            "region": "CA",
            "postcode": "92802",
            "country": "US"
        },
        "links": {},
        "meta": {
            "display_price": {
                "with_tax": {
                    "amount": 237500,
                    "currency": "USD",
                    "formatted": "$2175.00"
                },
                "without_tax": {
                    "amount": 237500,
                    "currency": "USD",
                    "formatted": "$2175.00"
                }
            },
            "timestamps": {
                "created_at": "2018-04-16T10:11:59.715Z",
                "updated_at": "2018-04-16T10:11:59.715Z"
            }
        },
        "relationships": {
            "items": {
                "data": [
                    {
                        "type": "item",
                        "id": "de9fddf5-011b-4485-abf8-ebb8f53c39ff"
                    }
                ]
            }
        }
    }
}

Was this helpful?

Previous
Order Items

Learn

Docs