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

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

Error response

Should return the following

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

Examples

Successful response

Omit error from response body

{  
  "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

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

With omitted checkout details

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

With full checkout details

{  
"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

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

Error desponse

Should return the following

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

Examples

Successful response

Omit error from response body

{  
  "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

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

With omitted order details

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

With full order details

{  
  "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"  
    }  
  }  
}

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

{
  "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"
    }
  }
}