---
updatedAt: 2024-12-17T05:35:51.000Z
agentTools:
projectIndex: https://docs.tamara.co/llms.txt
---
# Cancel Order
This endpoint is requested to cancel or update the total order amount while order status on `authorised` (before the order is captured or shipping process is done). The order status value will be `canceled` or `updated` based on the modification applied to the total amount.
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"info": {
"title": "Tamara Public APIs v1.0",
"version": "1.0.0",
"contact": {}
},
"servers": [
{
"url": "https://{environment}.tamara.co/",
"variables": {
"environment": {
"enum": [
"api-sandbox",
"api"
],
"default": "api-sandbox",
"description": "Choose the environment you'd like to test on, either Sandbox (uses testing API tokens) `api-sandbox` or Production (uses live API tokens) `api`"
}
}
}
],
"components": {
"securitySchemes": {
"bearerToken": {
"type": "http",
"scheme": "bearer",
"description": "Enter the API token that is provided by Tamara to be sent in Authorization header."
}
}
},
"security": [
{
"bearerToken": []
}
],
"paths": {
"/orders/{order_id}/cancel": {
"post": {
"tags": [
"Online Checkout"
],
"summary": "Cancel Order",
"description": "This endpoint is requested to cancel or update the total order amount while order status on `authorised` (before the order is captured or shipping process is done). The order status value will be `canceled` or `updated` based on the modification applied to the total amount.",
"operationId": "cancelOrder",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"total_amount"
],
"properties": {
"total_amount": {
"type": "object",
"description": "Total amount to be charged back to consumer.",
"properties": {
"amount": {
"type": "number",
"example": 300,
"default": 300
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"shipping_amount": {
"type": "object",
"description": "Total amount for the shipping of the order.",
"properties": {
"amount": {
"type": "number",
"example": 300,
"minimum": 0,
"default": 0
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"tax_amount": {
"type": "object",
"description": "Total amount of taxes, if additionally applied.",
"properties": {
"amount": {
"type": "number",
"example": 100,
"minimum": 0,
"default": 100
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"discount_amount": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"example": 10,
"minimum": 0,
"default": 10
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"reference_id",
"type",
"name",
"sku",
"quantity",
"total_amount"
],
"description": "An array of objects to detail the items in this order as seperate objects for each item.",
"properties": {
"name": {
"type": "string",
"description": "Product name. `<=255 characters`",
"example": "Lego City 8601",
"maximum": 255
},
"quantity": {
"type": "number",
"description": "How many of this specific item is being purchased",
"example": 1
},
"reference_id": {
"type": "string",
"description": "The unique id of the item from merchant's side",
"example": "123"
},
"sku": {
"type": "string",
"description": "Product SKU. **`<= 128 characters`**",
"example": "SA-12436",
"maximum": 128
},
"item_url": {
"type": "string",
"description": "URL of the item from merchant's website. **`<= 1024 characters`**",
"format": "uri",
"example": "SA-12436",
"maximum": 1024
},
"image_url": {
"type": "string",
"description": "URL to an image of the product that can be later displayed to the customer. **`<= 1024 characters`**
**Size** = 2-3 MB maximum
**Resolution** WxH = 1024xY (the Y height of image should be small).",
"format": "uri",
"example": "SA-12436",
"maximum": 1024
},
"unit_price": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"example": 490
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR"
}
}
},
"tax_amount": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"example": 10,
"minimum": 0
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR"
}
}
},
"discount_amount": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"example": 100
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR"
}
}
},
"total_amount": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"example": "100"
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR"
}
}
},
"type": {
"type": "string",
"example": "Digital"
}
}
},
"default": [
{
"name": "Lego City 8601",
"type": "Digital",
"reference_id": "123",
"sku": "SA-12436",
"quantity": 1,
"discount_amount": {
"amount": 100,
"currency": "SAR"
},
"tax_amount": {
"amount": 10,
"currency": "SAR"
},
"unit_price": {
"amount": 490,
"currency": "SAR"
},
"total_amount": {
"amount": 100,
"currency": "SAR"
}
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"properties": {
"cancel_id": {
"type": "string",
"format": "uuid"
},
"order_id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"updated",
"canceled"
]
},
"canceled_amount": {
"items": {
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"KWD",
"BHD",
"OMR"
]
}
}
}
}
},
"x-readme-ref-name": "cancel"
},
"examples": {
"Updated": {
"value": {
"order_id": "870e3e2e-e88a-4933-9ec0-7f7b8ed65e0c",
"cancel_id": "fecc5fce-2079-4292-8761-40726253f0bf",
"status": "updated",
"canceled_amount": {
"amount": 100,
"currency": "SAR"
}
}
},
"Canceled": {
"value": {
"order_id": "870e3e2e-e88a-4933-9ec0-7f7b8ed65e0c",
"cancel_id": "2c58ce01-04af-4387-9450-269ff822b558",
"status": "canceled",
"canceled_amount": {
"amount": 300,
"currency": "SAR"
}
}
}
}
}
}
},
"409": {
"description": "Cannot cancel orders in `approved` state",
"content": {
"application/json": {
"example": {
"message": "The order 870e3e2e-e88a-4933-9ec0-7f7b8ed65e0c cannot be moved to the status canceled from approved",
"errors": [
{
"error_code": "transition_not_allowed",
"data": {
"order_id": "870e3e2e-e88a-4933-9ec0-7f7b8ed65e0c",
"old_state": "approved",
"new_state": "canceled"
}
}
],
"data": {},
"title": null,
"screen_type": null
}
}
}
}
}
},
"parameters": [
{
"name": "order_id",
"in": "path",
"required": true,
"description": "Unique Tamara `order_id`, obtained from the response of create checkout/in-store checkout session endpoint.",
"schema": {
"type": "string",
"format": "uuid",
"example": "ff776045-513b-4cd7-8b4f-e60673daad84",
"default": "ff776045-513b-4cd7-8b4f-e60673daad84"
}
}
]
}
},
"tags": [
{
"name": "Online Checkout"
}
],
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true,
"samples-languages": [
"json",
"shell",
"python",
"php",
"swift",
"http",
"java",
"kotlin",
"r",
"ruby",
"node",
"javascript",
"c",
"csharp",
"cplusplus",
"go",
"objectivec"
]
}
}
```