# Acknowledgement API Reference



When an order is completed with being processed on the Commerce Platform (fraud checks, remorse period, ...), its state is automatically changed to `CREATED`. Acknowledging an order confirms that you have moved the order into your Order Management System and are ready to fulfill it. Acknowledging an order changes its state to `IN_PROGRESS`.

**Note:** By default, your shop is configured to automatically move orders to the `IN_PROGRESS` state when finalized. To enable order acknowledgement, you must first associate your shop with your app. This one-time operation is recommended if you are planning to fulfill orders using the API, and will leave finalized orders in the `CREATED` state until you acknowledge them.

## Associate Commerce Seller Settings with Your App {#order_management_apps}

To manage orders via API, an app must first be associated with the commerce seller settings representing your shop. **This action only needs to be performed once**, and instructs the Commerce Platform to leave finalized orders in the `CREATED` state for you to acknowledge.  

```html
curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<CMS_ID>/order_management_apps
```

**Note:** The token here is `PAGE_ACCESS_TOKEN`

### Request
| Attribute | Description |
| --- | --- |
| `cms-id`<br><br>Type: string | Commerce seller settings ID for the page that you want to extract orders. You can find `{cms-id}` by logging into [Facebook Commerce Manager](https://www.facebook.com/commerce_manager) and then select the page that you want to extract orders. You will be redirected to www.facebook.com/<br>commerce_manager/`{cms-id}` |

### Sample Response

```json
{
    "success": true
}
```

## Acknowledge One Order {#acknowledge_order}

Acknowledge one specific order that was retrieved using the [List Orders API](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-api). This action marks the order as `IN_PROGRESS`, and can be filtered out from future pulls.

**Warning:** Be sure to capture errors, take action according to the error messages, and retry accordingly. **Do not start processing orders in your systems that have not been successfully acknowledged.**

```html
curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/acknowledge_order
```

**Note:** The token here is `PAGE_ACCESS_TOKEN`

### Request

| Attribute | Description |
| --- | --- |
| `merchant_order_reference`<br><br>Type: string | **Optional**<br><br>ID representing the order in your order management system. |
| `idempotency_key`<br><br>Type: string | **Required**<br><br>Unique key per request |

### Sample Request

```json
{
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5163bec88b65",
  "merchant_order_reference": "external_order-id-1"
}
```

### Sample Response

```json
{
  "id": "64000841784004",
  "state": "IN_PROGRESS"
}
```

## Acknowledge Multiple Orders {#acknowledge_orders}

**Warning:** Acknowledge order batches have a maximum of 100 orders per batch.

Acknowledge orders that were received by the [List Orders API](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-api), in a batch. This action marks orders as `IN_PROGRESS`, and can be filtered out from future pulls.

```html
curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/acknowledge_orders
```

**Note:** The token here is `PAGE_ACCESS_TOKEN`

### Request

| Attribute | Description |
| --- | --- |
| `orders`<br>Type: `array` of [`order_id`](#order_id) | **Required**<br><br>Array of 100 or less order IDs. |
| `idempotency_key`<br><br>Type: string | **Required**<br><br>Unique key per request |

### `order_id` object {#order_id}
| Attribute | Description |
| --- | --- |
| `id`<br><br>Type: string | **Required**<br><br>ID of the order. |
| `merchant_order_reference`<br><br>Type: string | **Optional**<br><br>ID representing the order in your order management system |

**Warning:** You can Acknowledge multiple orders in one request. If few orders were in `FB_PROCESSING` state, then you **cannot ACK** them and receive a **coded exception**. Retrying these requests with same idempotency key returns the same result. **When you get a coded exception, please use new idempotency key and retry.**

### Sample Request

```json
{
  "idempotency_key": "cb090e84-e75a-9a34-45d3-5163bec88b65",
  "orders": [
    {
      "id": "64000841790004"
    },
    {
      "id": "10100677592885259"
    }
  ]
}
```

### Response

| Attribute | Description |
| --- | --- |
| `orders`<br><br>Type: `array` of [`order_id_and_state`](#order_id_and_state) | Array of order ID and order state. |

#### `order_id_and_state` object {#order_id_and_state}

| Attribute | Description |
| --- | --- |
| `id`<br><br>Type: string | ID of the order. |
| `state`<br><br>Type: [`order_state`](https://developers.facebook.com/docs/commerce-platform/order-management/overview#orders_states) | Order state. |

### Sample Response

```json
{
  "orders": [
    {
      "id": "64000841790004",
      "state": "IN_PROGRESS"
    },
    {
      "id": "10100677592885259",
      "error": {
        "error_code": 2361003,
        "error_message": "Invalid Order ID"
      }
    }
  ]
}
```