{ "openapi": "3.0.0", "info": { "title": "Corso Commerce API", "version": "0.9.0", "description": "\nThe Corso Commerce API is designed to be accessed by e-commerce systems that need to send orders to Corso for potential coverage under Green Shipping Protection. It is intended to be used in conjunction with the Corso Shop API, sending orders to Corso that have been quoted for Green Shipping Protection and where the customer has elected to purchase it.\n\n## Prerequisites\n\nBecause this API is authenticated, it requires a Client ID and Client Secret. Please contact us in order to generate this auth pair if needed.\n\nYour fulfillment locations (warehouses where items are shipped to the customer from) must also be set up with Corso. This information is used to calculate carbon emissions, to complete the \"Green\" part of Green Shipping Protection.\n\nVarious other pre-requisites will likely have already been completed for use of the Shop API, including the configuration of the Corso Green Shipping Protection products and variants.\n\n## Authentication\n\nThis API uses the **OAuth2 Client Credentials** flow. Request a JWT access token from the token endpoint using your `client_id` and `client_secret`, then include it as a Bearer token in the `Authorization` header of all API requests.\n\n| Environment | Token URL | Audience | API Base URL |\n|---|---|---|---|\n| Production | `https://auth.corso.com/oauth/token` | `api.corso.com` | `https://api.corso.com/v1` |\n| Staging | `https://auth.stg.corso.com/oauth/token` | `api.stg.corso.com` | `https://api.stg.corso.com/v1` |\n\n**Example token request:**\n```bash\ncurl -X POST \"https://auth.corso.com/oauth/token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"client_id\": \"YOUR_CLIENT_ID\",\n \"client_secret\": \"YOUR_CLIENT_SECRET\",\n \"audience\": \"api.corso.com\",\n \"grant_type\": \"client_credentials\"\n }'\n```\n\n\n## Date/Time Format\n\nAll times are 'date-time' formatted strings, as one of the built-in formats officially defined by the Open API Specification: https://swagger.io/docs/specification/data-models/data-types/#string. Any date-time strings received without an offset will cause the request to fail.\n ", "contact": { "email": "support@corso.com" } }, "servers": [ { "url": "https://api.corso.com/v1" }, { "url": "https://api.stg.corso.com/v1" } ], "tags": [ { "name": "Orders", "description": "Data and operations to manage orders." }, { "name": "Store", "description": "Data and operations needed to manage a store." }, { "name": "Fulfillments", "description": "Data and operations to manage fulfillments." }, { "name": "Line Items", "description": "Data and operations to manage order line items." }, { "name": "Claims", "description": "Data and operations to manage claims (returns/exchanges)." }, { "name": "Shipping Claims", "description": "Data and operations to manage shipping protection claims." }, { "name": "Registrations", "description": "Data and operations to manage product registrations." }, { "name": "Webhooks", "description": "Corso webhooks send real-time HTTP POST notifications to your endpoint when important events occur. Subscribe to topics in Corso Admin and Corso delivers signed JSON payloads. See the Authenticating section for HMAC signature verification details." } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://auth.corso.com/oauth/token", "scopes": {} } }, "description": "OAuth2 Client Credentials flow. Request a JWT from the token URL using your `client_id`, `client_secret`, the `audience` value, and `grant_type` of `client_credentials`. Include the resulting token as a Bearer token in the Authorization header. See the Authentication section below for environment-specific configuration." } }, "schemas": { "Order": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "currencyConversionRate": { "type": "number", "description": "The conversion rate between store and customer" }, "storeId": { "type": "number", "example": 9359, "description": "The ID of the store in Corso systems. Some merchants may have multiple stores under a single API client_id, so this value should always be specified. Please contact Corso if you do not have this value for your integration." }, "isShippingProtected": { "type": "boolean", "example": true, "description": "Whether or not the order is protected with Corso Green Shipping Protection." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" }, "customer": { "allOf": [ { "type": "object", "properties": { "sourceCustomerId": { "type": "string", "description": "The customer ID from the source system.", "example": "990986" }, "firstName": { "type": "string", "description": "First name.", "example": "George" }, "lastName": { "type": "string", "description": "Last name.", "example": "Washington" } }, "required": [ "sourceCustomerId", "firstName", "lastName" ] }, { "anyOf": [ { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email address.", "example": "gwashington@mtvernon.org" }, "phone": { "type": "string", "description": "Customer phone number in E-164 format.", "example": "+16643443554" } }, "required": [ "email" ] }, { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email address.", "example": "gwashington@mtvernon.org" }, "phone": { "type": "string", "description": "Customer phone number in E-164 format.", "example": "+16643443554" } }, "required": [ "phone" ] } ] } ], "description": "Object representing the customer who placed the order." }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "number", "description": "The ID of the order the line item belongs to in Corso systems.", "example": 18372912 }, "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceCanceledOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was canceled in Corso systems." }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the line item was created in Corso systems." }, "updatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the line item was last updated in Corso systems." }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "tax": { "type": "number", "description": "Any tax applied to the line item.", "example": 1.23, "format": "currency" }, "vendor": { "type": "string", "description": "The vendor of the line item", "example": "Nike" }, "price": { "type": "number", "description": "The price of the line item", "example": 129.53, "format": "currency" }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The option name (e.g., \"Size\", \"Color\").", "example": "Size" }, "value": { "type": "string", "description": "The option value (e.g., \"Large\", \"Blue\").", "example": "Large" } }, "required": [ "name", "value" ] }, "description": "Product variant options from the platform.", "example": [ { "name": "Size", "value": "Large" }, { "name": "Color", "value": "Blue" } ] } }, "required": [ "orderId", "lineItemId", "sourceLineItemId", "name", "quantity", "sku", "tax", "price" ] }, "minItems": 1, "description": "Array of objects representing the line items on the order." }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "updatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was most recently updated in Corso systems." }, "sourceCanceledOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was canceled in the source system." }, "sourceCreatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in the source system." }, "sourceUpdatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was most recently updated in the source system" }, "shippingMoney": { "type": "number", "format": "currency", "example": 1, "description": "The cost of shipping the order as charged to the customer." }, "subtotalMoney": { "type": "number", "format": "currency", "example": 10, "description": "The subtotal of the order in the merchant's currency; typically equal to the cost of all product line items in the order totalled together." }, "taxMoney": { "type": "number", "format": "currency", "example": 1, "description": "The amount of all tax applied to the order as included in the order total." }, "totalMoney": { "type": "number", "format": "currency", "example": 12, "description": "The total amount charged to the customer. Must be equal to the sum of shippingMoney, subtotalMoney, and taxMoney, or the request will fail." }, "billingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "grams": { "type": "number", "description": "The weight of the order, in grams.", "example": 8783 }, "carbonGrams": { "type": "number", "description": "The amount of carbon offset for the order, in grams. Only available after fulfillment (when the shipping origin can be determined).", "example": 1338 }, "carbonCalculationMethod": { "type": "string", "description": "How the carbon was calculated, depending on the accuracy of the input data such as weight and distance.", "example": "Calculated" }, "shippingTitle": { "type": "string", "description": "The name of the shipping plan used.", "example": "FedEx 2nd Day Air" }, "canceledReason": { "type": "string", "description": "The reason the order was canceled.", "example": "Order was created by mistake" }, "notes": { "type": "string", "description": "Any notes on the order", "example": "Please use your red gift wrap, thank you!" }, "channel": { "type": "string", "description": "The name of the channel the order was created on.", "example": "web" }, "channelId": { "type": "string", "description": "The ID of the sales channel the order was created from.", "example": "d2d3d4d5" }, "customerCurrencyCode": { "type": "string", "description": "The 3 letter currency code used by the customer in ISO 4217 format", "example": "USD" } }, "required": [ "storeId", "sourceOrderId", "customer", "lineItems", "shippingMoney", "subtotalMoney", "taxMoney", "totalMoney", "billingAddress", "shippingAddress" ], "additionalProperties": false }, "OrderList": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "currencyConversionRate": { "type": "number", "description": "The conversion rate between store and customer" }, "storeId": { "type": "number", "example": 9359, "description": "The ID of the store in Corso systems. Some merchants may have multiple stores under a single API client_id, so this value should always be specified. Please contact Corso if you do not have this value for your integration." }, "isShippingProtected": { "type": "boolean", "example": true, "description": "Whether or not the order is protected with Corso Green Shipping Protection." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" }, "customer": { "allOf": [ { "type": "object", "properties": { "sourceCustomerId": { "type": "string", "description": "The customer ID from the source system.", "example": "990986" }, "firstName": { "type": "string", "description": "First name.", "example": "George" }, "lastName": { "type": "string", "description": "Last name.", "example": "Washington" } }, "required": [ "sourceCustomerId", "firstName", "lastName" ] }, { "anyOf": [ { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email address.", "example": "gwashington@mtvernon.org" }, "phone": { "type": "string", "description": "Customer phone number in E-164 format.", "example": "+16643443554" } }, "required": [ "email" ] }, { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email address.", "example": "gwashington@mtvernon.org" }, "phone": { "type": "string", "description": "Customer phone number in E-164 format.", "example": "+16643443554" } }, "required": [ "phone" ] } ] } ], "description": "Object representing the customer who placed the order." }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "number", "description": "The ID of the order the line item belongs to in Corso systems.", "example": 18372912 }, "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceCanceledOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was canceled in Corso systems." }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the line item was created in Corso systems." }, "updatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the line item was last updated in Corso systems." }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "tax": { "type": "number", "description": "Any tax applied to the line item.", "example": 1.23, "format": "currency" }, "vendor": { "type": "string", "description": "The vendor of the line item", "example": "Nike" }, "price": { "type": "number", "description": "The price of the line item", "example": 129.53, "format": "currency" }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The option name (e.g., \"Size\", \"Color\").", "example": "Size" }, "value": { "type": "string", "description": "The option value (e.g., \"Large\", \"Blue\").", "example": "Large" } }, "required": [ "name", "value" ] }, "description": "Product variant options from the platform.", "example": [ { "name": "Size", "value": "Large" }, { "name": "Color", "value": "Blue" } ] } }, "required": [ "orderId", "lineItemId", "sourceLineItemId", "name", "quantity", "sku", "tax", "price" ] }, "minItems": 1, "description": "Array of objects representing the line items on the order." }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "updatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was most recently updated in Corso systems." }, "sourceCanceledOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was canceled in the source system." }, "sourceCreatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in the source system." }, "sourceUpdatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was most recently updated in the source system" }, "shippingMoney": { "type": "number", "format": "currency", "example": 1, "description": "The cost of shipping the order as charged to the customer." }, "subtotalMoney": { "type": "number", "format": "currency", "example": 10, "description": "The subtotal of the order in the merchant's currency; typically equal to the cost of all product line items in the order totalled together." }, "taxMoney": { "type": "number", "format": "currency", "example": 1, "description": "The amount of all tax applied to the order as included in the order total." }, "totalMoney": { "type": "number", "format": "currency", "example": 12, "description": "The total amount charged to the customer. Must be equal to the sum of shippingMoney, subtotalMoney, and taxMoney, or the request will fail." }, "billingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "grams": { "type": "number", "description": "The weight of the order, in grams.", "example": 8783 }, "carbonGrams": { "type": "number", "description": "The amount of carbon offset for the order, in grams. Only available after fulfillment (when the shipping origin can be determined).", "example": 1338 }, "carbonCalculationMethod": { "type": "string", "description": "How the carbon was calculated, depending on the accuracy of the input data such as weight and distance.", "example": "Calculated" }, "shippingTitle": { "type": "string", "description": "The name of the shipping plan used.", "example": "FedEx 2nd Day Air" }, "canceledReason": { "type": "string", "description": "The reason the order was canceled.", "example": "Order was created by mistake" }, "notes": { "type": "string", "description": "Any notes on the order", "example": "Please use your red gift wrap, thank you!" }, "channel": { "type": "string", "description": "The name of the channel the order was created on.", "example": "web" }, "channelId": { "type": "string", "description": "The ID of the sales channel the order was created from.", "example": "d2d3d4d5" }, "customerCurrencyCode": { "type": "string", "description": "The 3 letter currency code used by the customer in ISO 4217 format", "example": "USD" } }, "required": [ "storeId", "sourceOrderId", "customer", "lineItems", "shippingMoney", "subtotalMoney", "taxMoney", "totalMoney", "billingAddress", "shippingAddress" ], "additionalProperties": false } }, "pageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean", "description": "Whether there are more items after the last returned item.", "example": true }, "hasPreviousPage": { "type": "boolean", "description": "Whether there are more items before the first returned item.", "example": false }, "startCursor": { "type": "string", "nullable": true, "description": "An opaque cursor pointing to the first item in the current page. Pass as `before` to paginate backwards.", "example": "eyJpZCI6MTIzNDU2fQ" }, "endCursor": { "type": "string", "nullable": true, "description": "An opaque cursor pointing to the last item in the current page. Pass as `after` to paginate forwards.", "example": "eyJpZCI6Nzg5MDEyfQ" } }, "required": [ "hasNextPage", "hasPreviousPage", "startCursor", "endCursor" ], "description": "Information about the pagination of a list." } }, "required": [ "orders", "pageInfo" ] }, "Fulfillment": { "type": "object", "properties": { "sourceFulfillmentId": { "type": "string", "example": "ACME-FULFILL-439823", "description": "The ID of the fulfillment, as recorded in merchant systems." }, "shippingWeightGrams": { "type": "number", "description": "The weight of the fulfillment in grams" }, "fulfillmentId": { "type": "number", "description": "The Corso ID of the fulfillment record" }, "fulfillmentLocationId": { "type": "number", "description": "The Corso ID of the location the order is fulfilled from." }, "deliveredOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": " Date/time when the fulfillment was delivered." }, "trackingInfoCompany": { "type": "string", "description": "The courier used to ship the fulfillment.", "example": "USPS" }, "trackingInfoNumber": { "type": "string", "description": "The tracking number for the fulfillment.", "example": "UPS-12345" }, "trackingInfoUrl": { "type": "string", "format": "url", "description": "The URL to track the fulfillment.", "example": "https://www.ups.com/track?loc=en_US&tracknum=1Z12345E0291980793" }, "estimatedDeliveryOn": { "type": "string", "format": "date-time", "description": "Date/time when the fulfillment is estimated to be delivered on." }, "shipmentStatus": { "type": "string", "description": "The status of the shipment.", "example": "in_transit" }, "inTransitOn": { "type": "string", "format": "date-time", "description": "Date/time when the fulfillment was shipped." }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the fulfillment was created Corso systems." }, "updatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the fulfillment was updated in Corso systems." }, "sourceCreatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the fulfillment was created in the source system." } }, "required": [ "sourceFulfillmentId", "fulfillmentId", "fulfillmentLocationId" ] }, "FulfillmentList": { "type": "object", "properties": { "fulfillments": { "type": "array", "items": { "type": "object", "properties": { "sourceFulfillmentId": { "type": "string", "example": "ACME-FULFILL-439823", "description": "The ID of the fulfillment, as recorded in merchant systems." }, "shippingWeightGrams": { "type": "number", "description": "The weight of the fulfillment in grams" }, "fulfillmentId": { "type": "number", "description": "The Corso ID of the fulfillment record" }, "fulfillmentLocationId": { "type": "number", "description": "The Corso ID of the location the order is fulfilled from." }, "deliveredOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": " Date/time when the fulfillment was delivered." }, "trackingInfoCompany": { "type": "string", "description": "The courier used to ship the fulfillment.", "example": "USPS" }, "trackingInfoNumber": { "type": "string", "description": "The tracking number for the fulfillment.", "example": "UPS-12345" }, "trackingInfoUrl": { "type": "string", "format": "url", "description": "The URL to track the fulfillment.", "example": "https://www.ups.com/track?loc=en_US&tracknum=1Z12345E0291980793" }, "estimatedDeliveryOn": { "type": "string", "format": "date-time", "description": "Date/time when the fulfillment is estimated to be delivered on." }, "shipmentStatus": { "type": "string", "description": "The status of the shipment.", "example": "in_transit" }, "inTransitOn": { "type": "string", "format": "date-time", "description": "Date/time when the fulfillment was shipped." }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the fulfillment was created Corso systems." }, "updatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the fulfillment was updated in Corso systems." }, "sourceCreatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the fulfillment was created in the source system." } }, "required": [ "sourceFulfillmentId", "fulfillmentId", "fulfillmentLocationId" ] } } }, "required": [ "fulfillments" ] }, "LineItem": { "type": "object", "properties": { "orderId": { "type": "number", "description": "The ID of the order the line item belongs to in Corso systems.", "example": 18372912 }, "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceCanceledOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was canceled in Corso systems." }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the line item was created in Corso systems." }, "updatedOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the line item was last updated in Corso systems." }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "tax": { "type": "number", "description": "Any tax applied to the line item.", "example": 1.23, "format": "currency" }, "vendor": { "type": "string", "description": "The vendor of the line item", "example": "Nike" }, "price": { "type": "number", "description": "The price of the line item", "example": 129.53, "format": "currency" }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The option name (e.g., \"Size\", \"Color\").", "example": "Size" }, "value": { "type": "string", "description": "The option value (e.g., \"Large\", \"Blue\").", "example": "Large" } }, "required": [ "name", "value" ] }, "description": "Product variant options from the platform.", "example": [ { "name": "Size", "value": "Large" }, { "name": "Color", "value": "Blue" } ] } }, "required": [ "orderId", "lineItemId", "sourceLineItemId", "name", "quantity", "sku", "tax", "price" ] }, "Store": { "type": "object", "properties": { "storeId": { "type": "number", "description": "The ID of the store in Corso systems. Most operations will require a store ID, since an authenticated API connection could potentially have permissions to manage resources for multiple stores.", "example": 6734 }, "currencyCode": { "type": "string", "description": "The 3 letter currency code used by the store (in ISO 4217 format). This currency code is used as the basis for all money values transmitted via the API including order totals, line item values, and similar.", "example": "USD" }, "ianaTimezone": { "type": "string", "description": "The timezone for the store. Used as a factor when calculating invoice time periods, reorder windows, and similar time-based evaluations.", "example": "America/Denver" } }, "required": [ "storeId", "currencyCode", "ianaTimezone" ] }, "Claim": { "type": "object", "properties": { "storeId": { "type": "number", "description": "The Corso ID of the store that the claim belongs to.", "example": 123456 }, "claimId": { "type": "number", "description": "The Corso ID of the claim.", "example": 456789 }, "externalId": { "type": "string", "description": "The external claim ID, used for customer-facing references.", "example": "1-123-1" }, "resolutionSummary": { "type": "object", "properties": { "giftCards": { "type": "array", "items": { "type": "object", "properties": { "giftCardId": { "type": "number", "description": "The Corso ID of the gift card.", "example": 123456 }, "amount": { "type": "number", "description": "The amount of the gift card.", "example": 100, "format": "currency" }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the gift card was created.", "example": "2024-01-20T14:45:00Z" } }, "required": [ "giftCardId", "amount" ] } }, "refunds": { "type": "array", "items": { "type": "object", "properties": { "refundId": { "type": "number", "description": "The Corso ID of the refund.", "example": 123456 }, "amount": { "type": "number", "description": "The amount of the refund.", "example": 100, "format": "currency" }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the refund was created.", "example": "2024-01-20T14:45:00Z" } }, "required": [ "refundId", "amount" ] } }, "replacementOrders": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] } } }, "required": [ "sourceOrderId", "lineItems" ], "additionalProperties": false } } }, "required": [ "giftCards", "refunds", "replacementOrders" ], "description": "The resolution summary of the claim, consists of what was actually issued when the claim was finalized.", "example": { "refunds": [] } }, "wasCreatedFromRegistration": { "type": "boolean", "description": "Whether the claim was created from a registration order.", "example": false }, "requestSummary": { "type": "object", "properties": { "monetaryTotals": { "type": "object", "properties": { "giftCard": { "type": "number", "description": "The total amount of gift cards in the request summary.", "example": 100, "format": "currency" }, "refund": { "type": "number", "description": "The total amount of refunds set to be approved when the claim is finalized.", "example": 100, "format": "currency" } }, "required": [ "giftCard", "refund" ] }, "approvedLineItems": { "type": "array", "items": { "type": "object", "properties": { "claimLineItemId": { "type": "number", "description": "The Corso ID of the claim line item.", "example": 123456 }, "quantity": { "type": "number", "description": "The quantity of items in this claim line item.", "example": 1 }, "amount": { "type": "number", "description": "The issued monetary value of this claim line item in the store currency.", "example": 49.99, "format": "currency" }, "resolutionMethod": { "type": "string", "enum": [ "Refund", "Variant_Exchange", "Gift_Card", "Repair", "Replacement_Order", "Warranty_Review", "Other" ], "description": "The resolution method of the line item, may be different from the requested resolution method if the claim line item value was applied to a replacement order or other deduction.", "example": "Refund" }, "estimatedAmount": { "type": "number", "description": "The estimated amount of the line item, accounting for deductions across all line items.", "example": 100, "format": "currency" }, "wasZeroedThroughDeduction": { "type": "boolean", "description": "Whether the line item was zeroed through deduction, applies to claim line items where the amount was applied to a replacement order or other deduction." } }, "required": [ "claimLineItemId", "quantity", "amount" ] }, "description": "The line items set to be approved when the claim is finalized." } }, "required": [ "monetaryTotals", "approvedLineItems" ], "description": "A snapshot of the current estimate of what will be issued when the claim is finalized. This represents the pending state of approvals and resolutions. This property does not exist after the claim is finalized, please use Resolution Summary instead.", "example": { "monetaryTotals": { "giftCard": 100, "refund": 100 }, "approvedLineItems": [ { "claimLineItemId": 123456, "quantity": 1, "amount": 100, "resolutionMethod": "Refund", "estimatedAmount": 100, "wasZeroedThroughDeduction": false } ] } }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "billingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "currencyCode": { "type": "string", "description": "The currency code of the claim.", "example": "USD" }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "shipmentId": { "type": "number", "description": "The Corso ID of the shipment.", "example": 123456 }, "toAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "fromAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "expiresOn": { "type": "string", "format": "date-time", "description": "The date/time when the shipment expires.", "example": "2024-01-20T14:45:00Z" }, "inTransitOn": { "type": "string", "format": "date-time", "description": "The date/time when the shipment was put in transit.", "example": "2024-01-20T14:45:00Z" }, "isReturnShipment": { "type": "boolean", "description": "Whether the shipment is a return shipment.", "example": true }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the shipment was created.", "example": "2024-01-20T14:45:00Z" }, "qrCodeUrl": { "type": "string", "description": "The URL to retrieve the QR code for the shipment.", "example": "https://cdn.corso.com/img/qr-code.png" }, "labelUrl": { "type": "string", "description": "The URL to retrieve the label for the shipment, if applicable.", "example": "https://cdn.corso.com/img/label.png" }, "packingSlipUrl": { "type": "string", "description": "The URL to retrieve the packing slip for the shipment, if applicable.", "example": "https://cdn.corso.com/img/packing-slip.pdf" }, "method": { "type": "string", "enum": [ "Packing_Slip", "Label" ], "description": "The method of the shipment.", "example": "Label" }, "carrier": { "type": "string", "description": "The carrier of the shipment.", "example": "USPS" }, "carrierTrackingUrl": { "type": "string", "description": "The URL of the carrier tracking page.", "example": "https://www.usps.com/tracking/1234567890" }, "carrierTrackingStatus": { "type": "string", "description": "The status of the carrier tracking.", "example": "In Transit" }, "carrierServiceName": { "type": "string", "description": "The name of the carrier service.", "example": "USPS" } }, "required": [ "shipmentId", "toAddress", "fromAddress", "isReturnShipment", "method" ] }, "description": "The shipments associated with the claim." }, "order": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" } }, "required": [ "sourceOrderId" ], "additionalProperties": false }, "isInstantExchange": { "type": "boolean", "description": "Whether this claim is an instant exchange.", "example": false }, "claimType": { "type": "string", "enum": [ "Warranty", "Return" ], "description": "The type of claim.", "example": "Return" }, "status": { "type": "string", "enum": [ "In_Progress", "Ready_For_Review", "Completed" ], "description": "The rollup status of the claim.", "example": "In_Progress" }, "feeAmountApplied": { "type": "number", "description": "The amount of the fee applied to the claim.", "example": 10, "format": "currency" }, "feeName": { "type": "string", "description": "The name of the fee applied to the claim.", "example": "Handling Fee" }, "exchangeOrderShippingAmountApplied": { "type": "number", "description": "The amount of the shipping applied to the exchange order.", "example": 10, "format": "currency" }, "returnShippingAmountApplied": { "type": "number", "description": "The amount of the shipping applied to the return order.", "example": 10, "format": "currency" }, "shopNowIncentiveAmountApplied": { "type": "number", "description": "The amount of the shop now incentive applied to the claim.", "example": 10, "format": "currency" }, "customerEmail": { "type": "string", "description": "The email address of the customer who filed the claim, may be different from the email on the order.", "example": "customer@example.com" }, "customerName": { "type": "string", "description": "The name of the customer who filed the claim.", "example": "John Doe" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags applied to this claim for categorization.", "example": [ "VIP", "Urgent" ] }, "claimLineItems": { "type": "array", "items": { "type": "object", "properties": { "sourceLineItem": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] }, "claimLineItemId": { "type": "number", "description": "The Corso ID of the claim line item.", "example": 123456 }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom field.", "example": "Serial Number" }, "value": { "type": "string", "description": "The value of the custom field." } }, "required": [ "name", "value" ] } }, "quantity": { "type": "number", "description": "The quantity of items in this claim line item.", "example": 1 }, "variantExchangeLineItem": { "type": "object", "properties": { "variantId": { "type": "string", "description": "The variant ID of the exchange line item in the source system.", "example": "var-123456" }, "quantity": { "type": "number", "description": "The quantity of the exchange line item.", "example": 1 }, "price": { "type": "number", "description": "The price of the exchange line item.", "example": 10, "format": "currency" }, "imgUrl": { "type": "string", "description": "The URL of the image of the exchange line item.", "example": "https://cdn.corso.com/img/exchange-item.png" }, "sku": { "type": "string", "description": "The SKU of the exchange line item.", "example": "123456" }, "title": { "type": "string", "description": "The title of the exchange line item.", "example": "Exchange Item" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the option.", "example": "Color" }, "value": { "type": "string", "description": "The value of the option.", "example": "Red" } }, "required": [ "name", "value" ] }, "description": "The options of the exchange line item.", "example": [ { "name": "Color", "value": "Red" }, { "name": "Size", "value": "M" } ] } }, "required": [ "variantId", "quantity", "price" ], "description": "The variant exchange line item associated with this claim line item, if applicable.", "example": { "variantId": "123456", "quantity": 1, "price": 10 } }, "isShopNow": { "type": "boolean", "description": "Whether this claim line item resulted from a shop now session.", "example": false }, "replacementItems": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "description": "The variant ID of the exchange line item in the source system.", "example": "var-123456" }, "quantity": { "type": "number", "description": "The quantity of the exchange line item.", "example": 1 }, "price": { "type": "number", "description": "The price of the exchange line item.", "example": 10, "format": "currency" }, "imgUrl": { "type": "string", "description": "The URL of the image of the exchange line item.", "example": "https://cdn.corso.com/img/exchange-item.png" }, "sku": { "type": "string", "description": "The SKU of the exchange line item.", "example": "123456" }, "title": { "type": "string", "description": "The title of the exchange line item.", "example": "Exchange Item" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the option.", "example": "Color" }, "value": { "type": "string", "description": "The value of the option.", "example": "Red" } }, "required": [ "name", "value" ] }, "description": "The options of the exchange line item.", "example": [ { "name": "Color", "value": "Red" }, { "name": "Size", "value": "M" } ] } }, "required": [ "variantId", "quantity", "price" ] }, "description": "The replacement items associated with this claim line item, if applicable.", "example": [ { "variantId": "var-123456", "quantity": 1, "price": 10 } ] }, "amount": { "type": "number", "description": "The issued monetary value of this claim line item in the store currency.", "example": 49.99, "format": "currency" }, "requestedAmount": { "type": "number", "description": "The requested monetary value of this claim line item in the store currency.", "example": 49.99, "format": "currency" }, "reason": { "type": "string", "description": "The name of the reason selected for this claim line item.", "example": "Wrong Size" }, "reasonDetail": { "type": "string", "description": "The name of the reason detail selected for this claim line item, if applicable.", "example": "Too Small" }, "status": { "type": "string", "enum": [ "Open", "Approved", "Denied", "Closed", "Awaiting_Return", "In_Transit", "At_Return_Location" ], "description": "The status of the claim line item.", "example": "Open" }, "statusDetail": { "type": "string", "enum": [ "Final_Sale", "Pending_Review", "Pending_Additional_Info", "Awaiting_Customer_Dropoff_Label_Provided", "Awaiting_Customer_Dropoff_Packing_Slip_Provided", "In_Transit", "Pending_Inspection", "Pending_Approval", "Variant_Exchange", "Gift_Card_Issued", "Refunded", "Refunded_Partial", "Gift_Card_Issued_Partial", "Replacement_Order", "Repaired", "Wrong_Item", "Item_Not_Returned", "Noncompliant_Return", "Not_Covered_Under_Warranty", "Pending_Return_Shipment_Creation", "Return_Not_Required", "Additional_Info_Not_Provided", "No_Action_Taken", "Item_Credit_Applied_To_Claim" ], "description": "The status detail of the claim line item.", "example": "Pending_Review" }, "imageUrls": { "type": "array", "items": { "type": "string" }, "description": "The images associated with the claim line item.", "example": [ "https://cdn.corso.com/img/corso-gsp-prod-img.png" ] }, "requestedResolutionMethod": { "type": "string", "enum": [ "Refund", "Variant_Exchange", "Gift_Card", "Repair", "Replacement_Order", "Warranty_Review", "Other" ], "description": "The resolution method requested by the customer for this line item.", "example": "Refund" }, "resolutionMethod": { "type": "string", "enum": [ "Refund", "Variant_Exchange", "Gift_Card", "Repair", "Replacement_Order", "Warranty_Review", "Other" ], "description": "The actual resolution method applied to this line item, if resolved.", "example": "Gift_Card" }, "noteFromCustomer": { "type": "string", "description": "Notes provided by the customer about the claim line item.", "example": "Item was damaged in transit." }, "deniedOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim line item was denied.", "example": "2024-01-20T14:45:00Z" }, "canceledOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim line item was canceled.", "example": "2024-01-20T14:45:00Z" } }, "required": [ "sourceLineItem", "claimLineItemId", "customFields", "quantity", "isShopNow", "amount", "requestedAmount", "reason", "status", "statusDetail", "requestedResolutionMethod" ] }, "description": "The line items included in this claim." }, "noteToCustomer": { "type": "string", "description": "Notes provided by the merchant about the claim.", "example": "Fulfillment issue - tracking not updating." }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was created.", "example": "2024-01-20T14:45:00Z" }, "updatedOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was last updated.", "example": "2024-01-21T09:15:00Z" }, "finalizedOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was finalized, if applicable.", "example": "2024-01-22T16:00:00Z" } }, "required": [ "storeId", "claimId", "externalId", "wasCreatedFromRegistration", "shippingAddress", "billingAddress", "currencyCode", "order", "isInstantExchange", "claimType", "status", "feeAmountApplied", "exchangeOrderShippingAmountApplied", "returnShippingAmountApplied", "shopNowIncentiveAmountApplied", "customerEmail", "tags", "claimLineItems" ] }, "ClaimList": { "type": "object", "properties": { "claims": { "type": "array", "items": { "type": "object", "properties": { "storeId": { "type": "number", "description": "The Corso ID of the store that the claim belongs to.", "example": 123456 }, "claimId": { "type": "number", "description": "The Corso ID of the claim.", "example": 456789 }, "externalId": { "type": "string", "description": "The external claim ID, used for customer-facing references.", "example": "1-123-1" }, "resolutionSummary": { "type": "object", "properties": { "giftCards": { "type": "array", "items": { "type": "object", "properties": { "giftCardId": { "type": "number", "description": "The Corso ID of the gift card.", "example": 123456 }, "amount": { "type": "number", "description": "The amount of the gift card.", "example": 100, "format": "currency" }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the gift card was created.", "example": "2024-01-20T14:45:00Z" } }, "required": [ "giftCardId", "amount" ] } }, "refunds": { "type": "array", "items": { "type": "object", "properties": { "refundId": { "type": "number", "description": "The Corso ID of the refund.", "example": 123456 }, "amount": { "type": "number", "description": "The amount of the refund.", "example": 100, "format": "currency" }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the refund was created.", "example": "2024-01-20T14:45:00Z" } }, "required": [ "refundId", "amount" ] } }, "replacementOrders": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] } } }, "required": [ "sourceOrderId", "lineItems" ], "additionalProperties": false } } }, "required": [ "giftCards", "refunds", "replacementOrders" ], "description": "The resolution summary of the claim, consists of what was actually issued when the claim was finalized.", "example": { "refunds": [] } }, "wasCreatedFromRegistration": { "type": "boolean", "description": "Whether the claim was created from a registration order.", "example": false }, "requestSummary": { "type": "object", "properties": { "monetaryTotals": { "type": "object", "properties": { "giftCard": { "type": "number", "description": "The total amount of gift cards in the request summary.", "example": 100, "format": "currency" }, "refund": { "type": "number", "description": "The total amount of refunds set to be approved when the claim is finalized.", "example": 100, "format": "currency" } }, "required": [ "giftCard", "refund" ] }, "approvedLineItems": { "type": "array", "items": { "type": "object", "properties": { "claimLineItemId": { "type": "number", "description": "The Corso ID of the claim line item.", "example": 123456 }, "quantity": { "type": "number", "description": "The quantity of items in this claim line item.", "example": 1 }, "amount": { "type": "number", "description": "The issued monetary value of this claim line item in the store currency.", "example": 49.99, "format": "currency" }, "resolutionMethod": { "type": "string", "enum": [ "Refund", "Variant_Exchange", "Gift_Card", "Repair", "Replacement_Order", "Warranty_Review", "Other" ], "description": "The resolution method of the line item, may be different from the requested resolution method if the claim line item value was applied to a replacement order or other deduction.", "example": "Refund" }, "estimatedAmount": { "type": "number", "description": "The estimated amount of the line item, accounting for deductions across all line items.", "example": 100, "format": "currency" }, "wasZeroedThroughDeduction": { "type": "boolean", "description": "Whether the line item was zeroed through deduction, applies to claim line items where the amount was applied to a replacement order or other deduction." } }, "required": [ "claimLineItemId", "quantity", "amount" ] }, "description": "The line items set to be approved when the claim is finalized." } }, "required": [ "monetaryTotals", "approvedLineItems" ], "description": "A snapshot of the current estimate of what will be issued when the claim is finalized. This represents the pending state of approvals and resolutions. This property does not exist after the claim is finalized, please use Resolution Summary instead.", "example": { "monetaryTotals": { "giftCard": 100, "refund": 100 }, "approvedLineItems": [ { "claimLineItemId": 123456, "quantity": 1, "amount": 100, "resolutionMethod": "Refund", "estimatedAmount": 100, "wasZeroedThroughDeduction": false } ] } }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "billingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "currencyCode": { "type": "string", "description": "The currency code of the claim.", "example": "USD" }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "shipmentId": { "type": "number", "description": "The Corso ID of the shipment.", "example": 123456 }, "toAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "fromAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ] }, "expiresOn": { "type": "string", "format": "date-time", "description": "The date/time when the shipment expires.", "example": "2024-01-20T14:45:00Z" }, "inTransitOn": { "type": "string", "format": "date-time", "description": "The date/time when the shipment was put in transit.", "example": "2024-01-20T14:45:00Z" }, "isReturnShipment": { "type": "boolean", "description": "Whether the shipment is a return shipment.", "example": true }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the shipment was created.", "example": "2024-01-20T14:45:00Z" }, "qrCodeUrl": { "type": "string", "description": "The URL to retrieve the QR code for the shipment.", "example": "https://cdn.corso.com/img/qr-code.png" }, "labelUrl": { "type": "string", "description": "The URL to retrieve the label for the shipment, if applicable.", "example": "https://cdn.corso.com/img/label.png" }, "packingSlipUrl": { "type": "string", "description": "The URL to retrieve the packing slip for the shipment, if applicable.", "example": "https://cdn.corso.com/img/packing-slip.pdf" }, "method": { "type": "string", "enum": [ "Packing_Slip", "Label" ], "description": "The method of the shipment.", "example": "Label" }, "carrier": { "type": "string", "description": "The carrier of the shipment.", "example": "USPS" }, "carrierTrackingUrl": { "type": "string", "description": "The URL of the carrier tracking page.", "example": "https://www.usps.com/tracking/1234567890" }, "carrierTrackingStatus": { "type": "string", "description": "The status of the carrier tracking.", "example": "In Transit" }, "carrierServiceName": { "type": "string", "description": "The name of the carrier service.", "example": "USPS" } }, "required": [ "shipmentId", "toAddress", "fromAddress", "isReturnShipment", "method" ] }, "description": "The shipments associated with the claim." }, "order": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" } }, "required": [ "sourceOrderId" ], "additionalProperties": false }, "isInstantExchange": { "type": "boolean", "description": "Whether this claim is an instant exchange.", "example": false }, "claimType": { "type": "string", "enum": [ "Warranty", "Return" ], "description": "The type of claim.", "example": "Return" }, "status": { "type": "string", "enum": [ "In_Progress", "Ready_For_Review", "Completed" ], "description": "The rollup status of the claim.", "example": "In_Progress" }, "feeAmountApplied": { "type": "number", "description": "The amount of the fee applied to the claim.", "example": 10, "format": "currency" }, "feeName": { "type": "string", "description": "The name of the fee applied to the claim.", "example": "Handling Fee" }, "exchangeOrderShippingAmountApplied": { "type": "number", "description": "The amount of the shipping applied to the exchange order.", "example": 10, "format": "currency" }, "returnShippingAmountApplied": { "type": "number", "description": "The amount of the shipping applied to the return order.", "example": 10, "format": "currency" }, "shopNowIncentiveAmountApplied": { "type": "number", "description": "The amount of the shop now incentive applied to the claim.", "example": 10, "format": "currency" }, "customerEmail": { "type": "string", "description": "The email address of the customer who filed the claim, may be different from the email on the order.", "example": "customer@example.com" }, "customerName": { "type": "string", "description": "The name of the customer who filed the claim.", "example": "John Doe" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags applied to this claim for categorization.", "example": [ "VIP", "Urgent" ] }, "claimLineItems": { "type": "array", "items": { "type": "object", "properties": { "sourceLineItem": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] }, "claimLineItemId": { "type": "number", "description": "The Corso ID of the claim line item.", "example": 123456 }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom field.", "example": "Serial Number" }, "value": { "type": "string", "description": "The value of the custom field." } }, "required": [ "name", "value" ] } }, "quantity": { "type": "number", "description": "The quantity of items in this claim line item.", "example": 1 }, "variantExchangeLineItem": { "type": "object", "properties": { "variantId": { "type": "string", "description": "The variant ID of the exchange line item in the source system.", "example": "var-123456" }, "quantity": { "type": "number", "description": "The quantity of the exchange line item.", "example": 1 }, "price": { "type": "number", "description": "The price of the exchange line item.", "example": 10, "format": "currency" }, "imgUrl": { "type": "string", "description": "The URL of the image of the exchange line item.", "example": "https://cdn.corso.com/img/exchange-item.png" }, "sku": { "type": "string", "description": "The SKU of the exchange line item.", "example": "123456" }, "title": { "type": "string", "description": "The title of the exchange line item.", "example": "Exchange Item" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the option.", "example": "Color" }, "value": { "type": "string", "description": "The value of the option.", "example": "Red" } }, "required": [ "name", "value" ] }, "description": "The options of the exchange line item.", "example": [ { "name": "Color", "value": "Red" }, { "name": "Size", "value": "M" } ] } }, "required": [ "variantId", "quantity", "price" ], "description": "The variant exchange line item associated with this claim line item, if applicable.", "example": { "variantId": "123456", "quantity": 1, "price": 10 } }, "isShopNow": { "type": "boolean", "description": "Whether this claim line item resulted from a shop now session.", "example": false }, "replacementItems": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "description": "The variant ID of the exchange line item in the source system.", "example": "var-123456" }, "quantity": { "type": "number", "description": "The quantity of the exchange line item.", "example": 1 }, "price": { "type": "number", "description": "The price of the exchange line item.", "example": 10, "format": "currency" }, "imgUrl": { "type": "string", "description": "The URL of the image of the exchange line item.", "example": "https://cdn.corso.com/img/exchange-item.png" }, "sku": { "type": "string", "description": "The SKU of the exchange line item.", "example": "123456" }, "title": { "type": "string", "description": "The title of the exchange line item.", "example": "Exchange Item" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the option.", "example": "Color" }, "value": { "type": "string", "description": "The value of the option.", "example": "Red" } }, "required": [ "name", "value" ] }, "description": "The options of the exchange line item.", "example": [ { "name": "Color", "value": "Red" }, { "name": "Size", "value": "M" } ] } }, "required": [ "variantId", "quantity", "price" ] }, "description": "The replacement items associated with this claim line item, if applicable.", "example": [ { "variantId": "var-123456", "quantity": 1, "price": 10 } ] }, "amount": { "type": "number", "description": "The issued monetary value of this claim line item in the store currency.", "example": 49.99, "format": "currency" }, "requestedAmount": { "type": "number", "description": "The requested monetary value of this claim line item in the store currency.", "example": 49.99, "format": "currency" }, "reason": { "type": "string", "description": "The name of the reason selected for this claim line item.", "example": "Wrong Size" }, "reasonDetail": { "type": "string", "description": "The name of the reason detail selected for this claim line item, if applicable.", "example": "Too Small" }, "status": { "type": "string", "enum": [ "Open", "Approved", "Denied", "Closed", "Awaiting_Return", "In_Transit", "At_Return_Location" ], "description": "The status of the claim line item.", "example": "Open" }, "statusDetail": { "type": "string", "enum": [ "Final_Sale", "Pending_Review", "Pending_Additional_Info", "Awaiting_Customer_Dropoff_Label_Provided", "Awaiting_Customer_Dropoff_Packing_Slip_Provided", "In_Transit", "Pending_Inspection", "Pending_Approval", "Variant_Exchange", "Gift_Card_Issued", "Refunded", "Refunded_Partial", "Gift_Card_Issued_Partial", "Replacement_Order", "Repaired", "Wrong_Item", "Item_Not_Returned", "Noncompliant_Return", "Not_Covered_Under_Warranty", "Pending_Return_Shipment_Creation", "Return_Not_Required", "Additional_Info_Not_Provided", "No_Action_Taken", "Item_Credit_Applied_To_Claim" ], "description": "The status detail of the claim line item.", "example": "Pending_Review" }, "imageUrls": { "type": "array", "items": { "type": "string" }, "description": "The images associated with the claim line item.", "example": [ "https://cdn.corso.com/img/corso-gsp-prod-img.png" ] }, "requestedResolutionMethod": { "type": "string", "enum": [ "Refund", "Variant_Exchange", "Gift_Card", "Repair", "Replacement_Order", "Warranty_Review", "Other" ], "description": "The resolution method requested by the customer for this line item.", "example": "Refund" }, "resolutionMethod": { "type": "string", "enum": [ "Refund", "Variant_Exchange", "Gift_Card", "Repair", "Replacement_Order", "Warranty_Review", "Other" ], "description": "The actual resolution method applied to this line item, if resolved.", "example": "Gift_Card" }, "noteFromCustomer": { "type": "string", "description": "Notes provided by the customer about the claim line item.", "example": "Item was damaged in transit." }, "deniedOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim line item was denied.", "example": "2024-01-20T14:45:00Z" }, "canceledOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim line item was canceled.", "example": "2024-01-20T14:45:00Z" } }, "required": [ "sourceLineItem", "claimLineItemId", "customFields", "quantity", "isShopNow", "amount", "requestedAmount", "reason", "status", "statusDetail", "requestedResolutionMethod" ] }, "description": "The line items included in this claim." }, "noteToCustomer": { "type": "string", "description": "Notes provided by the merchant about the claim.", "example": "Fulfillment issue - tracking not updating." }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was created.", "example": "2024-01-20T14:45:00Z" }, "updatedOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was last updated.", "example": "2024-01-21T09:15:00Z" }, "finalizedOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was finalized, if applicable.", "example": "2024-01-22T16:00:00Z" } }, "required": [ "storeId", "claimId", "externalId", "wasCreatedFromRegistration", "shippingAddress", "billingAddress", "currencyCode", "order", "isInstantExchange", "claimType", "status", "feeAmountApplied", "exchangeOrderShippingAmountApplied", "returnShippingAmountApplied", "shopNowIncentiveAmountApplied", "customerEmail", "tags", "claimLineItems" ] } }, "pageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean", "description": "Whether there are more items after the last returned item.", "example": true }, "hasPreviousPage": { "type": "boolean", "description": "Whether there are more items before the first returned item.", "example": false }, "startCursor": { "type": "string", "nullable": true, "description": "An opaque cursor pointing to the first item in the current page. Pass as `before` to paginate backwards.", "example": "eyJpZCI6MTIzNDU2fQ" }, "endCursor": { "type": "string", "nullable": true, "description": "An opaque cursor pointing to the last item in the current page. Pass as `after` to paginate forwards.", "example": "eyJpZCI6Nzg5MDEyfQ" } }, "required": [ "hasNextPage", "hasPreviousPage", "startCursor", "endCursor" ], "description": "Information about the pagination of a list." } }, "required": [ "claims", "pageInfo" ] }, "ShippingClaim": { "type": "object", "properties": { "shippingClaimId": { "type": "number", "description": "The Corso ID of the shipping protection claim.", "example": 456789 }, "storeId": { "type": "number", "description": "The Corso ID of the store that the shipping protection claim belongs to.", "example": 123456 }, "status": { "type": "string", "enum": [ "Closed_Denied", "Closed_Refunded", "Closed_Reordered", "Closed_Resolved", "InProgress", "Open" ], "description": "The status of the shipping protection claim.", "example": "Open" }, "reason": { "type": "string", "enum": [ "Damaged", "Lost", "Stolen", "Wrong_Item", "Missing_Item", "Quality_Issue", "Incorrect_Address", "Satisfaction_Guarantee" ], "description": "The reason for the shipping protection claim.", "example": "Lost" }, "resolutionSummary": { "type": "object", "properties": { "refunds": { "type": "array", "items": { "type": "object", "properties": { "refundId": { "type": "number", "description": "The Corso ID of the refund.", "example": 123456 }, "amount": { "type": "number", "description": "The amount of the refund.", "example": 100, "format": "currency" }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the refund was created.", "example": "2024-01-20T14:45:00Z" } }, "required": [ "refundId", "amount" ] } }, "reorders": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] } } }, "required": [ "sourceOrderId", "lineItems" ], "additionalProperties": false } } }, "required": [ "refunds", "reorders" ], "description": "The resolution summary of the claim, consists of what was actually issued when the claim was finalized.", "example": { "refunds": [], "reorders": [] } }, "resolutionMethod": { "type": "string", "enum": [ "Refund", "Reorder" ], "description": "The resolution method applied to this claim, if resolved.", "example": "Refund" }, "source": { "type": "string", "enum": [ "Customer_App", "Merchant_App", "Retool", "Gorgias_Ticket_Widget", "Zowie_Inbox_Integration", "Gladly_Hero_Integration", "Kustomer_App_Integration", "Zendesk_App_Integration", "Public_API" ], "description": "The source from which the claim was created.", "example": "Customer_App" }, "customerEmail": { "type": "string", "description": "The email address of the customer who filed the claim.", "example": "customer@example.com" }, "order": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" } }, "required": [ "sourceOrderId" ], "additionalProperties": false, "description": "The order associated with the shipping protection claim." }, "noteFromCustomer": { "type": "string", "description": "Notes provided by the customer about the claim.", "example": "Package never arrived at my doorstep." }, "noteFromMerchant": { "type": "string", "description": "Notes added by the merchant about the claim.", "example": "Verified with carrier. Approved for refund." }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ], "description": "The shipping address for the claim, when creating a new claim this can be used to provide an address different from the order address." }, "claimLineItems": { "type": "array", "items": { "type": "object", "properties": { "claimLineItemId": { "type": "number", "description": "The Corso ID of the shipping protection claim line item.", "example": 123456 }, "quantity": { "type": "number", "description": "The quantity of items in this claim line item.", "example": 1 }, "sourceLineItem": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] } }, "required": [ "claimLineItemId", "quantity", "sourceLineItem" ] }, "description": "The line items included in this shipping protection claim." }, "images": { "type": "array", "items": { "type": "string" }, "description": "URLs to images uploaded by the customer for the claim.", "example": [ "https://cdn.example.com/claims/img1.jpg", "https://cdn.example.com/claims/img2.jpg" ] }, "currencyCode": { "type": "string", "description": "The currency code for monetary values in the claim.", "example": "USD" }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was created.", "example": "2024-01-20T14:45:00Z" }, "finalizedOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was finalized, if applicable.", "example": "2024-01-22T16:00:00Z" } }, "required": [ "shippingClaimId", "storeId", "status", "reason", "order", "claimLineItems" ] }, "ShippingClaimList": { "type": "object", "properties": { "shippingClaims": { "type": "array", "items": { "type": "object", "properties": { "shippingClaimId": { "type": "number", "description": "The Corso ID of the shipping protection claim.", "example": 456789 }, "storeId": { "type": "number", "description": "The Corso ID of the store that the shipping protection claim belongs to.", "example": 123456 }, "status": { "type": "string", "enum": [ "Closed_Denied", "Closed_Refunded", "Closed_Reordered", "Closed_Resolved", "InProgress", "Open" ], "description": "The status of the shipping protection claim.", "example": "Open" }, "reason": { "type": "string", "enum": [ "Damaged", "Lost", "Stolen", "Wrong_Item", "Missing_Item", "Quality_Issue", "Incorrect_Address", "Satisfaction_Guarantee" ], "description": "The reason for the shipping protection claim.", "example": "Lost" }, "resolutionSummary": { "type": "object", "properties": { "refunds": { "type": "array", "items": { "type": "object", "properties": { "refundId": { "type": "number", "description": "The Corso ID of the refund.", "example": 123456 }, "amount": { "type": "number", "description": "The amount of the refund.", "example": 100, "format": "currency" }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the refund was created.", "example": "2024-01-20T14:45:00Z" } }, "required": [ "refundId", "amount" ] } }, "reorders": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] } } }, "required": [ "sourceOrderId", "lineItems" ], "additionalProperties": false } } }, "required": [ "refunds", "reorders" ], "description": "The resolution summary of the claim, consists of what was actually issued when the claim was finalized.", "example": { "refunds": [], "reorders": [] } }, "resolutionMethod": { "type": "string", "enum": [ "Refund", "Reorder" ], "description": "The resolution method applied to this claim, if resolved.", "example": "Refund" }, "source": { "type": "string", "enum": [ "Customer_App", "Merchant_App", "Retool", "Gorgias_Ticket_Widget", "Zowie_Inbox_Integration", "Gladly_Hero_Integration", "Kustomer_App_Integration", "Zendesk_App_Integration", "Public_API" ], "description": "The source from which the claim was created.", "example": "Customer_App" }, "customerEmail": { "type": "string", "description": "The email address of the customer who filed the claim.", "example": "customer@example.com" }, "order": { "type": "object", "properties": { "orderId": { "type": "number", "example": 18372912, "description": "The ID of the order in Corso, used to interact with Corso systems." }, "sourceOrderId": { "type": "string", "example": "842810", "description": "The order identifier from the source platform. Is unique across the store, and typically across the entire platform used by the merchant." }, "orderNumber": { "type": "string", "description": "The order number from the source platform, if none is provided. sourceOrderId will be used" }, "createdOn": { "type": "string", "format": "date-time", "example": "2022-01-01T17:32:28Z", "description": "Date/time when the order was created in Corso systems." }, "orderName": { "type": "string", "description": "Customer-facing identifier for the order the source platform. Often composed of the store-unique order number plus some modifying prefixes and suffixes.", "example": "RDR-12345" } }, "required": [ "sourceOrderId" ], "additionalProperties": false, "description": "The order associated with the shipping protection claim." }, "noteFromCustomer": { "type": "string", "description": "Notes provided by the customer about the claim.", "example": "Package never arrived at my doorstep." }, "noteFromMerchant": { "type": "string", "description": "Notes added by the merchant about the claim.", "example": "Verified with carrier. Approved for refund." }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ], "description": "The shipping address for the claim, when creating a new claim this can be used to provide an address different from the order address." }, "claimLineItems": { "type": "array", "items": { "type": "object", "properties": { "claimLineItemId": { "type": "number", "description": "The Corso ID of the shipping protection claim line item.", "example": 123456 }, "quantity": { "type": "number", "description": "The quantity of items in this claim line item.", "example": 1 }, "sourceLineItem": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] } }, "required": [ "claimLineItemId", "quantity", "sourceLineItem" ] }, "description": "The line items included in this shipping protection claim." }, "images": { "type": "array", "items": { "type": "string" }, "description": "URLs to images uploaded by the customer for the claim.", "example": [ "https://cdn.example.com/claims/img1.jpg", "https://cdn.example.com/claims/img2.jpg" ] }, "currencyCode": { "type": "string", "description": "The currency code for monetary values in the claim.", "example": "USD" }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was created.", "example": "2024-01-20T14:45:00Z" }, "finalizedOn": { "type": "string", "format": "date-time", "description": "The date/time when the claim was finalized, if applicable.", "example": "2024-01-22T16:00:00Z" } }, "required": [ "shippingClaimId", "storeId", "status", "reason", "order", "claimLineItems" ] } }, "pageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean", "description": "Whether there are more items after the last returned item.", "example": true }, "hasPreviousPage": { "type": "boolean", "description": "Whether there are more items before the first returned item.", "example": false }, "startCursor": { "type": "string", "nullable": true, "description": "An opaque cursor pointing to the first item in the current page. Pass as `before` to paginate backwards.", "example": "eyJpZCI6MTIzNDU2fQ" }, "endCursor": { "type": "string", "nullable": true, "description": "An opaque cursor pointing to the last item in the current page. Pass as `after` to paginate forwards.", "example": "eyJpZCI6Nzg5MDEyfQ" } }, "required": [ "hasNextPage", "hasPreviousPage", "startCursor", "endCursor" ], "description": "Information about the pagination of a list." } }, "required": [ "shippingClaims", "pageInfo" ] }, "Registration": { "type": "object", "properties": { "registrationId": { "type": "number", "description": "The Corso ID of the registration.", "example": 789012 }, "storeId": { "type": "number", "description": "The Corso ID of the store that the registration belongs to.", "example": 123456 }, "externalId": { "type": "string", "description": "The external registration ID, used for customer-facing references.", "example": "REG-1-456" }, "customerEmail": { "type": "string", "description": "The email address of the customer who created the registration.", "example": "customer@example.com" }, "customerName": { "type": "string", "description": "The name of the customer who created the registration.", "example": "Jane Doe" }, "channelName": { "type": "string", "description": "The name of the registration channel.", "example": "Online Store" }, "customerProvidedOrderNumber": { "type": "string", "description": "The order number provided by the customer during registration, if applicable.", "example": "#1580" }, "estimatedPurchaseDate": { "type": "string", "format": "date-time", "description": "The estimated date of purchase provided by the customer, if applicable.", "example": "2024-06-15T00:00:00Z" }, "referrer": { "type": "string", "description": "The referrer URL or source for this registration.", "example": "https://example.com/products/widget" }, "emailMarketingConsent": { "type": "boolean", "description": "Whether the customer consented to email marketing during registration.", "example": true }, "emailMarketingConsentCollectedOn": { "type": "string", "format": "date-time", "description": "The date/time when email marketing consent was collected, if applicable.", "example": "2024-01-20T14:45:00Z" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] }, "description": "The product line items associated with this registration." }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom field.", "example": "Serial Number" }, "value": { "type": "string", "description": "The value of the custom field.", "example": "SN-12345-AB" } }, "required": [ "name", "value" ] }, "description": "Custom field values captured during registration." }, "proofOfPurchaseFileUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs to proof-of-purchase files uploaded by the customer.", "example": [ "https://cdn.example.com/registrations/receipt1.jpg", "https://cdn.example.com/registrations/receipt2.jpg" ] }, "incentiveDiscounts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The discount code.", "example": "SAVE20" }, "message": { "type": "string", "description": "The message describing the discount.", "example": "Save 20% on your next purchase!" }, "redemptionUrl": { "type": "string", "description": "The URL where the discount can be redeemed, if applicable.", "example": "https://example.com/shop/pants" }, "expiresOn": { "type": "string", "format": "date-time", "description": "The expiration date of the discount, if applicable.", "example": "2024-12-31T23:59:59Z" } }, "required": [ "code" ] } }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the registration was created.", "example": "2024-01-20T14:45:00Z" }, "updatedOn": { "type": "string", "format": "date-time", "description": "The date/time when the registration was last updated.", "example": "2024-01-21T09:15:00Z" }, "canceledOn": { "type": "string", "format": "date-time", "description": "The date/time when the registration was canceled, if applicable.", "example": "2024-02-01T10:00:00Z" }, "claims": { "type": "array", "items": { "type": "object", "properties": { "claimId": { "type": "number", "description": "The Corso ID of the claim.", "example": 123456 }, "externalId": { "type": "string", "description": "The external ID of the claim.", "example": "1-123-1" }, "claimType": { "type": "string", "enum": [ "Warranty", "Return" ], "description": "The type of the claim." } }, "required": [ "claimId", "externalId", "claimType" ] } } }, "required": [ "registrationId", "storeId", "externalId", "customerEmail", "channelName", "emailMarketingConsent", "lineItems", "claims" ] }, "RegistrationList": { "type": "object", "properties": { "registrations": { "type": "array", "items": { "type": "object", "properties": { "registrationId": { "type": "number", "description": "The Corso ID of the registration.", "example": 789012 }, "storeId": { "type": "number", "description": "The Corso ID of the store that the registration belongs to.", "example": 123456 }, "externalId": { "type": "string", "description": "The external registration ID, used for customer-facing references.", "example": "REG-1-456" }, "customerEmail": { "type": "string", "description": "The email address of the customer who created the registration.", "example": "customer@example.com" }, "customerName": { "type": "string", "description": "The name of the customer who created the registration.", "example": "Jane Doe" }, "channelName": { "type": "string", "description": "The name of the registration channel.", "example": "Online Store" }, "customerProvidedOrderNumber": { "type": "string", "description": "The order number provided by the customer during registration, if applicable.", "example": "#1580" }, "estimatedPurchaseDate": { "type": "string", "format": "date-time", "description": "The estimated date of purchase provided by the customer, if applicable.", "example": "2024-06-15T00:00:00Z" }, "referrer": { "type": "string", "description": "The referrer URL or source for this registration.", "example": "https://example.com/products/widget" }, "emailMarketingConsent": { "type": "boolean", "description": "Whether the customer consented to email marketing during registration.", "example": true }, "emailMarketingConsentCollectedOn": { "type": "string", "format": "date-time", "description": "The date/time when email marketing consent was collected, if applicable.", "example": "2024-01-20T14:45:00Z" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "sourceLineItemId": { "type": "string", "description": "The line item ID (from the source system).", "example": "990986" }, "productId": { "type": "string", "description": "The product ID for the line item (from the source system).", "example": "pro-33320" }, "variantId": { "type": "string", "description": "The variant ID for the line item (from the source system). For the line item that represents the Corso Green Shipping Product (if purchased on the order), this should match the corresponding variant ID stored by Corso in our system, so that we can identify the order as protected.", "example": "var-4569876332" }, "sku": { "type": "string", "description": "The SKU of product/variant of the line item.", "example": "ITEM-12345" }, "name": { "type": "string", "description": "The line item name, typically the value shown to the customer representing the product/variant combination purchased.", "example": "Shorts - color: blue, size: small" }, "quantity": { "type": "number", "description": "The quantity purchased for the line item.", "example": 1 }, "imgUrl": { "type": "string", "description": "URL of the product image, if available.", "example": "https://cdn.example.com/products/widget-blue.jpg" } }, "required": [ "lineItemId", "sourceLineItemId", "sku", "name", "quantity" ] }, "description": "The product line items associated with this registration." }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom field.", "example": "Serial Number" }, "value": { "type": "string", "description": "The value of the custom field.", "example": "SN-12345-AB" } }, "required": [ "name", "value" ] }, "description": "Custom field values captured during registration." }, "proofOfPurchaseFileUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs to proof-of-purchase files uploaded by the customer.", "example": [ "https://cdn.example.com/registrations/receipt1.jpg", "https://cdn.example.com/registrations/receipt2.jpg" ] }, "incentiveDiscounts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The discount code.", "example": "SAVE20" }, "message": { "type": "string", "description": "The message describing the discount.", "example": "Save 20% on your next purchase!" }, "redemptionUrl": { "type": "string", "description": "The URL where the discount can be redeemed, if applicable.", "example": "https://example.com/shop/pants" }, "expiresOn": { "type": "string", "format": "date-time", "description": "The expiration date of the discount, if applicable.", "example": "2024-12-31T23:59:59Z" } }, "required": [ "code" ] } }, "createdOn": { "type": "string", "format": "date-time", "description": "The date/time when the registration was created.", "example": "2024-01-20T14:45:00Z" }, "updatedOn": { "type": "string", "format": "date-time", "description": "The date/time when the registration was last updated.", "example": "2024-01-21T09:15:00Z" }, "canceledOn": { "type": "string", "format": "date-time", "description": "The date/time when the registration was canceled, if applicable.", "example": "2024-02-01T10:00:00Z" }, "claims": { "type": "array", "items": { "type": "object", "properties": { "claimId": { "type": "number", "description": "The Corso ID of the claim.", "example": 123456 }, "externalId": { "type": "string", "description": "The external ID of the claim.", "example": "1-123-1" }, "claimType": { "type": "string", "enum": [ "Warranty", "Return" ], "description": "The type of the claim." } }, "required": [ "claimId", "externalId", "claimType" ] } } }, "required": [ "registrationId", "storeId", "externalId", "customerEmail", "channelName", "emailMarketingConsent", "lineItems", "claims" ] } }, "pageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean", "description": "Whether there are more items after the last returned item.", "example": true }, "hasPreviousPage": { "type": "boolean", "description": "Whether there are more items before the first returned item.", "example": false }, "startCursor": { "type": "string", "nullable": true, "description": "An opaque cursor pointing to the first item in the current page. Pass as `before` to paginate backwards.", "example": "eyJpZCI6MTIzNDU2fQ" }, "endCursor": { "type": "string", "nullable": true, "description": "An opaque cursor pointing to the last item in the current page. Pass as `after` to paginate forwards.", "example": "eyJpZCI6Nzg5MDEyfQ" } }, "required": [ "hasNextPage", "hasPreviousPage", "startCursor", "endCursor" ], "description": "Information about the pagination of a list." } }, "required": [ "registrations", "pageInfo" ] } }, "parameters": {} }, "paths": { "/stores/{storeId}": { "get": { "tags": [ "Store" ], "description": "This endpoint allows an API to retrieve data about Corso's representation of the store. This can be useful for verifying store properties used elsewhere by the API.", "summary": "Get a store", "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": true, "example": 428334, "description": "The Corso Id for the store", "name": "storeId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/orders": { "get": { "tags": [ "Orders" ], "description": "Retrieve a paginated list of orders for the authenticated store. Requires both customerEmail and orderNameOrNumber to filter orders. Optionally filter by sourceOrderId.", "summary": "List orders", "parameters": [ { "schema": { "type": "string", "description": "Required with orderNameOrNumber. The email address of the customer to filter orders by.", "example": "customer@example.com" }, "required": false, "description": "Required with orderNameOrNumber. The email address of the customer to filter orders by.", "in": "query", "name": "customerEmail" }, { "schema": { "type": "string", "description": "Required with customerEmail. The source order name or number to filter orders by.", "example": "RDR-12345" }, "required": false, "description": "Required with customerEmail. The source order name or number to filter orders by.", "in": "query", "name": "orderNameOrNumber" }, { "schema": { "type": "string", "description": "The order identifier from the source platform to filter by.", "example": "842810" }, "required": false, "description": "The order identifier from the source platform to filter by.", "in": "query", "name": "sourceOrderId" }, { "schema": { "type": "string", "description": "Cursor for forward pagination. Pass the `endCursor` from a previous response to fetch the next page.", "example": "eyJpZCI6MTIzNDU2fQ" }, "required": false, "description": "Cursor for forward pagination. Pass the `endCursor` from a previous response to fetch the next page.", "in": "query", "name": "after" }, { "schema": { "type": "string", "description": "Cursor for backward pagination. Pass the `startCursor` from a previous response to fetch the previous page.", "example": "eyJpZCI6Nzg5MDEyfQ" }, "required": false, "description": "Cursor for backward pagination. Pass the `startCursor` from a previous response to fetch the previous page.", "in": "query", "name": "before" }, { "schema": { "type": "number", "nullable": true, "description": "Number of items to return when paginating forward (used with `after`). Defaults to 50.", "example": 50 }, "required": false, "description": "Number of items to return when paginating forward (used with `after`). Defaults to 50.", "in": "query", "name": "first" }, { "schema": { "type": "number", "nullable": true, "description": "Number of items to return when paginating backward (used with `before`).", "example": 50 }, "required": false, "description": "Number of items to return when paginating backward (used with `before`).", "in": "query", "name": "last" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for results. Defaults to descending." }, "required": false, "description": "Sort order for results. Defaults to descending.", "in": "query", "name": "orderBy" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/orders/{orderId}": { "get": { "tags": [ "Orders" ], "description": "Retrieve the current representation of an order from Corso systems", "summary": "Get an order", "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": true, "example": 428334, "description": "The Corso ID for an order record.", "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/orders/{orderId}/fulfillments": { "get": { "tags": [ "Fulfillments" ], "description": "Retrieve all fulfillment records for an order. Records are not individually retrievable and this is the only endpoint available to read these resources.", "summary": "List order fulfillments", "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": true, "example": 428334, "description": "The Corso ID for an order record.", "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentList" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/orders/{orderId}/line-items/{lineItemId}": { "get": { "tags": [ "Line Items" ], "description": "Get a single line item from an order.", "summary": "Get a line Item", "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": true, "example": 12345, "description": "The Corso ID for a Line Item associated with an order.", "name": "lineItemId", "in": "path" }, { "schema": { "type": "number", "nullable": true }, "required": true, "example": 428334, "description": "The Corso ID for an order record.", "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineItem" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/claims/{claimId}": { "get": { "tags": [ "Claims" ], "description": "Retrieve a single claim (return/exchange) by its Corso ID.", "summary": "Get a claim", "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": true, "example": 456789, "description": "The Corso ID for the claim", "name": "claimId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/claims": { "get": { "tags": [ "Claims" ], "description": "Retrieve a list of claims (returns/exchanges) for the authenticated store.", "summary": "List claims", "parameters": [ { "schema": { "type": "string", "description": "The email address of the customer to filter claims by.", "example": "customer@example.com" }, "required": false, "description": "The email address of the customer to filter claims by.", "in": "query", "name": "customerEmail" }, { "schema": { "type": "string", "description": "The external ID of the claim to filter by.", "example": "1-123-1" }, "required": false, "description": "The external ID of the claim to filter by.", "in": "query", "name": "externalId" }, { "schema": { "type": "string", "description": "Cursor for forward pagination. Pass the `endCursor` from a previous response to fetch the next page.", "example": "eyJpZCI6MTIzNDU2fQ" }, "required": false, "description": "Cursor for forward pagination. Pass the `endCursor` from a previous response to fetch the next page.", "in": "query", "name": "after" }, { "schema": { "type": "string", "description": "Cursor for backward pagination. Pass the `startCursor` from a previous response to fetch the previous page.", "example": "eyJpZCI6Nzg5MDEyfQ" }, "required": false, "description": "Cursor for backward pagination. Pass the `startCursor` from a previous response to fetch the previous page.", "in": "query", "name": "before" }, { "schema": { "type": "number", "nullable": true, "description": "Number of items to return when paginating forward (used with `after`). Defaults to 50.", "example": 50 }, "required": false, "description": "Number of items to return when paginating forward (used with `after`). Defaults to 50.", "in": "query", "name": "first" }, { "schema": { "type": "number", "nullable": true, "description": "Number of items to return when paginating backward (used with `before`).", "example": 50 }, "required": false, "description": "Number of items to return when paginating backward (used with `before`).", "in": "query", "name": "last" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for results. Defaults to descending." }, "required": false, "description": "Sort order for results. Defaults to descending.", "in": "query", "name": "orderBy" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimList" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/shipping-claims/{shippingClaimId}": { "get": { "tags": [ "Shipping Claims" ], "description": "Retrieve a single shipping protection claim by its Corso ID.", "summary": "Get a shipping claim", "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": true, "example": 456789, "description": "The Corso ID for the shipping protection claim", "name": "shippingClaimId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingClaim" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/shipping-claims": { "get": { "tags": [ "Shipping Claims" ], "description": "Retrieve a list of shipping protection claims for the authenticated store.", "summary": "List shipping claims", "parameters": [ { "schema": { "type": "string", "description": "The order identifier from the source platform to filter claims by.", "example": "8908123123123109" }, "required": false, "description": "The order identifier from the source platform to filter claims by.", "in": "query", "name": "sourceOrderId" }, { "schema": { "type": "number", "nullable": true, "description": "The Corso order ID to filter claims by.", "example": 18372912 }, "required": false, "description": "The Corso order ID to filter claims by.", "in": "query", "name": "orderId" }, { "schema": { "type": "string", "description": "Cursor for forward pagination. Pass the `endCursor` from a previous response to fetch the next page.", "example": "eyJpZCI6MTIzNDU2fQ" }, "required": false, "description": "Cursor for forward pagination. Pass the `endCursor` from a previous response to fetch the next page.", "in": "query", "name": "after" }, { "schema": { "type": "string", "description": "Cursor for backward pagination. Pass the `startCursor` from a previous response to fetch the previous page.", "example": "eyJpZCI6Nzg5MDEyfQ" }, "required": false, "description": "Cursor for backward pagination. Pass the `startCursor` from a previous response to fetch the previous page.", "in": "query", "name": "before" }, { "schema": { "type": "number", "nullable": true, "description": "Number of items to return when paginating forward (used with `after`). Defaults to 50.", "example": 50 }, "required": false, "description": "Number of items to return when paginating forward (used with `after`). Defaults to 50.", "in": "query", "name": "first" }, { "schema": { "type": "number", "nullable": true, "description": "Number of items to return when paginating backward (used with `before`).", "example": 50 }, "required": false, "description": "Number of items to return when paginating backward (used with `before`).", "in": "query", "name": "last" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for results. Defaults to descending." }, "required": false, "description": "Sort order for results. Defaults to descending.", "in": "query", "name": "orderBy" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingClaimList" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } }, "post": { "tags": [ "Shipping Claims" ], "description": "Create a new shipping protection claim for an order. The order must be protected with Corso Shipping Protection or the request will fail. The claim must include at least one line item and a reason for the claim.", "summary": "Create a shipping claim", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "Damaged", "Lost", "Stolen", "Wrong_Item", "Missing_Item", "Quality_Issue", "Incorrect_Address", "Satisfaction_Guarantee" ], "description": "The reason for the shipping protection claim.", "example": "Lost" }, "noteFromCustomer": { "type": "string", "description": "Notes provided by the customer about the claim.", "example": "Package never arrived at my doorstep." }, "noteFromMerchant": { "type": "string", "description": "Notes added by the merchant about the claim.", "example": "Verified with carrier. Approved for refund." }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "The name line on an address. Often the name of the customer, or the business name something is shipped to.", "example": "Michael Jordan, c/o Chicago Bulls" }, "firstName": { "type": "string", "description": "The first name for the address.", "example": "John" }, "lastName": { "type": "string", "description": "The last name for the address.", "example": "Doe" }, "line1": { "type": "string", "description": "Address line 1, generally the street number and name.", "example": "1901 W Madison St" }, "line2": { "type": "string", "description": "Address line 2. Not mandatory, but often used for an apartment or suite number.", "example": "Ste 101" }, "city": { "type": "string", "description": "City of the Address", "example": "Chicago" }, "stateOrProvinceCode": { "type": "string", "description": "State or province code, typically 2 characters.", "example": "IL" }, "postalCode": { "type": "string", "description": "Postal Code", "example": "60612-2459" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "latitude": { "type": "number", "description": "Latitude coordinate of the address.", "example": 41.8807 }, "longitude": { "type": "number", "description": "Longitude coordinate of the address.", "example": -87.6742 } }, "required": [ "line1", "city", "stateOrProvinceCode", "postalCode", "countryCode" ], "description": "The shipping address for the claim, when creating a new claim this can be used to provide an address different from the order address." }, "orderId": { "type": "number", "description": "The ID of the order in Corso systems.", "example": 18372912 }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "number", "description": "The ID of the line item in Corso systems.", "example": 18372912 }, "quantity": { "type": "number", "description": "The quantity of items being claimed for this line item.", "example": 1 } }, "required": [ "lineItemId", "quantity" ] }, "minItems": 1, "description": "The line items to include in this shipping protection claim." }, "notifyCustomer": { "type": "boolean", "description": "Whether to notify the customer about this claim via Corso pre-configured email.", "example": true } }, "required": [ "reason", "orderId", "lineItems" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingClaim" } } } }, "400": { "description": "Bad Request - Order is not protected with Corso Green Shipping Protection, or request data is invalid." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "A shipping claim already exists for this order." }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/registrations/{registrationId}": { "get": { "tags": [ "Registrations" ], "description": "Retrieve a single product registration by its Corso ID.", "summary": "Get a registration", "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": true, "example": 789012, "description": "The Corso ID for the registration", "name": "registrationId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registration" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } }, "/registrations": { "get": { "tags": [ "Registrations" ], "description": "Retrieve a list of product registrations for the authenticated store. Supports filtering by customer email, channel name, or external ID.", "summary": "List registrations", "parameters": [ { "schema": { "type": "string", "description": "Filter registrations by customer email address.", "example": "customer@example.com" }, "required": false, "description": "Filter registrations by customer email address.", "in": "query", "name": "customerEmail" }, { "schema": { "type": "string", "description": "Filter registrations by channel name.", "example": "Online Store" }, "required": false, "description": "Filter registrations by channel name.", "in": "query", "name": "channelName" }, { "schema": { "type": "string", "description": "Filter registrations by external ID.", "example": "REG-1-456" }, "required": false, "description": "Filter registrations by external ID.", "in": "query", "name": "externalId" }, { "schema": { "type": "string", "description": "Cursor for forward pagination. Pass the `endCursor` from a previous response to fetch the next page.", "example": "eyJpZCI6MTIzNDU2fQ" }, "required": false, "description": "Cursor for forward pagination. Pass the `endCursor` from a previous response to fetch the next page.", "in": "query", "name": "after" }, { "schema": { "type": "string", "description": "Cursor for backward pagination. Pass the `startCursor` from a previous response to fetch the previous page.", "example": "eyJpZCI6Nzg5MDEyfQ" }, "required": false, "description": "Cursor for backward pagination. Pass the `startCursor` from a previous response to fetch the previous page.", "in": "query", "name": "before" }, { "schema": { "type": "number", "nullable": true, "description": "Number of items to return when paginating forward (used with `after`). Defaults to 50.", "example": 50 }, "required": false, "description": "Number of items to return when paginating forward (used with `after`). Defaults to 50.", "in": "query", "name": "first" }, { "schema": { "type": "number", "nullable": true, "description": "Number of items to return when paginating backward (used with `before`).", "example": 50 }, "required": false, "description": "Number of items to return when paginating backward (used with `before`).", "in": "query", "name": "last" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for results. Defaults to descending." }, "required": false, "description": "Sort order for results. Defaults to descending.", "in": "query", "name": "orderBy" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationList" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "The number of seconds until the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds to wait before retrying (only present when rate limited)." } } } } } } } }