---
updatedAt: 2026-09-07T11:12:57.000Z
agentTools:
  projectIndex: https://docs.nacelle.com/llms.txt
---

# Response Model Reference

Use these models as a reference for how commerce data needs to be returned (both success and errors) for Nacelle to process it correctly.

Merchant mappers should return data in the following format:

## Validation

### Model details

Checkout Details : Checkout Object

Error Details: Error API model

### Successful response

Should return the following

```json
{  
  "checkout":{...} //full checkout details  
}
```

### Error response

Should return the following

```json
{  
  "checkout":{...} //undefined or empty checkout details  
  "error":{...} //full error details  
}
```

## Examples

### Successful response

Omit error from response body

```json
{  
  "checkout": {  
    ...  
    "items": [  
      {  
        ...  
        "product_id": "...",  
        "variant_id": "...",  
        "quantity": 10,  
        "available": 8  
      }  
    ],  
    "meta_data": \[] // \<- Add any merchant notes to be used in the frontend  
  }  
}
```

### Error response

With empty checkout data

```json
{  
  "checkout": {},  
  "error": {  
    "error": "Promotion Code Invalid",  
    "category": "promotion_codes",  
    "details": {  
      "invalid-code": "XMAS-2021-25"  
    }  
  }  
}
```

With omitted checkout details

```json
{  
  "error": {  
    "error": "Promotion Code Invalid",  
    "category": "promotion_codes",  
    "details": {  
      "invalid-code": "XMAS-2021-25"  
    }  
  }  
}
```

With full checkout details

```json
{  
"checkout": {  
    ...  
    "items": [  
      {  
        ...  
        "product_id": "...",  
        "variant_id": "...",  
        "quantity": 10,  
        "available": 8  
      }  
    ]  
  },  
  "error": {  
    "error": "Promotion Code Invalid",  
    "category": "promotion_codes",  
    "details": {  
      "invalid-code": "XMAS-2021-25"  
    }  
  }  
}
```

## Consumption

### Model details

Order Details: OrderInput Object

Error Details: Error API model

### Successful desponse

Should return the following

```json
{  
  "order":{...} //full order details  
}
```

### Error desponse

Should return the following

```json
{  
  "order":{...} //undefined or empty order details  
  "error":{...} //full error details  
}
```

## Examples

### Successful response

Omit error from response body

```json
{  
  "order": {  
    ...  
    "items": [  
      {  
        ...  
        "product_id": "...",  
        "variant_id": "...",  
        "quantity": 10,  
        "available": 8  
      }  
    ]  
    "meta_data": \[] // \<- Add any merchant notes to be used in the frontend  
  }
}
```

### Error response

With empty order data

```json
{  
  "order": {},  
  "error": {  
    "error": "Promotion Code Invalid",  
    "category": "promotion_codes",  
    "details": {  
      "invalid-code": "XMAS-2021-25"  
    }  
  }  
}
```

With omitted order details

```json
{  
  "error": {  
    "error": "Promotion Code Invalid",  
    "category": "promotion_codes",  
    "details": {  
      "invalid-code": "XMAS-2021-25"  
    }  
  }  
}
```

With full order details

```json
{  
  "order": {  
    ...  
    "items": [  
      {  
        ...  
        "product_id": "...",  
        "variant_id": "...",  
        "quantity": 10,  
        "available": 8  
      }  
    ]  
    "meta_data": \[]  
  },  
  "error": {  
    "error": "Promotion Code Invalid",  
    "category": "promotion_codes",  
    "details": {  
      "invalid-code": "XMAS-2021-25"  
    }  
  }  
}
```

<br />

## Error responses

Any errors returned from merchant mappers should be structured in the following format:

| Field             | Description                                                                            |
| :---------------- | :------------------------------------------------------------------------------------- |
| error             | Merchant-defined error message                                                         |
| category          | Merchant-defined category to help with decoding error details,                         |
| details(optional) | Merchant-defined details based on the category, can include any json-serializable data |

Details should be tied to a specific category which will allow frontends to interpret the json object.

## Example

```json
{
  "error": "Partially out of stock",
  "category": "inventory",
  "details": {
    "item1-id": {
      "quantity": 0,
      "recommended_product_id": "test-product-123",
      "status": "out of stock"
    },
    "item2-id": {
      "quantity": 10,
      "status": "available"
    }
  }
}
```