--- title: Create Return Policy slug: api-documentation/create-return-policy docTags: createdAt: 2026-08-27T16:53:32.339Z --- { "id": "vDVT8goHVcSYjHvC8ZulE", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.upstartcommerce.com/v1/return-policy", "servers": [ { "url": "https://api.upstartcommerce.com/v1/return-policy" } ], "name": "Create Return Policy", "description": "This endpoint allows operators to create a new return policy.", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" }, { "kind": "required", "name": "x-upstart-tenant", "type": "string", "description": "Tenant identifier associated with the site this call is for." }, { "kind": "optional", "name": "x-upstart-site", "type": "string", "description": "Unique identifier for the site." } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "", "customType": "CreateReturnPolicy", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "Unique identifier for the return policy. If it is not provided a random one will be generated.", "format": "uuid" }, { "name": "siteIds", "kind": "required", "type": "array", "description": "", "modelRef": "#/components/schemas/SiteId", "customType": "SiteId[]", "schema": [] }, { "name": "name", "kind": "required", "type": "string", "description": "

A human-readable name of the return policy.

" }, { "name": "activationDate", "kind": "optional", "type": "string", "description": "

An optional date determining since when the return policy is activated. If it is not provided, the activation has no lower bound.

", "example": "2021-12-01T00:00:00Z", "format": "date-time" }, { "name": "archived", "kind": "optional", "type": "boolean", "description": "Determines whether the return policy is archived or not.", "default": false }, { "name": "deactivationDate", "kind": "optional", "type": "string", "description": "

An optional date determining until when the return policy is activated. If it is not provided, the activation has no upper bound.

", "example": "2021-12-21T00:30:00Z", "format": "date-time" }, { "name": "groups", "kind": "required", "type": "array", "description": "", "modelRef": "#/components/schemas/ReturnPolicyGroup", "customType": "ReturnPolicyGroup[]", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "

A human-readable name of this return policy group (e.g. King Size Mattress).

" }, { "name": "triggerGroup", "kind": "required", "type": "object", "description": "

A subject that might take place as a trigger or qualifier for a return policy. It can be a

\n
    \n
  • particular SKU or the whole product.
    • \n
", "modelRef": "#/components/schemas/ReturnPolicySubject", "customType": "ReturnPolicySubject[]", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ReturnPolicyProduct", "description": "", "modelRef": "#/components/schemas/ReturnPolicyProduct", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "" }, { "name": "id", "kind": "required", "type": "string", "description": "A product ID of the product." } ] }, { "name": "ReturnPolicySku", "description": "", "modelRef": "#/components/schemas/ReturnPolicySku", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "" }, { "name": "id", "kind": "required", "type": "string", "description": "A product ID of the product this SKU belongs to." }, { "name": "skuId", "kind": "required", "type": "string", "description": "An ID of this SKU." } ] } ] }, { "name": "qualifyingGroup", "kind": "required", "type": "object", "description": "

A subject that might take place as a trigger or qualifier for a return policy. It can be a

\n
    \n
  • particular SKU or the whole product.
    • \n
", "modelRef": "#/components/schemas/ReturnPolicySubject", "customType": "ReturnPolicySubject[]", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ReturnPolicyProduct", "description": "", "modelRef": "#/components/schemas/ReturnPolicyProduct", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "" }, { "name": "id", "kind": "required", "type": "string", "description": "A product ID of the product." } ] }, { "name": "ReturnPolicySku", "description": "", "modelRef": "#/components/schemas/ReturnPolicySku", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "" }, { "name": "id", "kind": "required", "type": "string", "description": "A product ID of the product this SKU belongs to." }, { "name": "skuId", "kind": "required", "type": "string", "description": "An ID of this SKU." } ] } ] } ] }, { "name": "triggeredTemplate", "kind": "required", "type": "string", "description": "A message template to be populated once this return policy is triggered by cart content." }, { "name": "unqualifiedTemplate", "kind": "required", "type": "string", "description": "A message template to be populated when this return policy is triggered by cart content but the cart content does not qualify for the return policy." } ], "modelRef": "#/components/schemas/CreateReturnPolicy", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "NoChannelPortalAccess", "name": "NoChannelPortalAccess", "kind": "optional", "type": "http", "description": "

This authentication is required for clients to interact with any of the management APIs. Similar to 'LoggedIn', it indicates that the user has actually logged into the system, but in this case with a management role.

", "scheme": "bearer" }, { "id": "SessionIdAccess", "name": "SessionIdAccess", "kind": "optional", "type": "http", "description": "This authentication is session based", "scheme": "bearer" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "201", "description": "

Success-return policy created.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ReturnPolicy", "schema": [ { "name": "id", "kind": "required", "type": "string", "description": "Unique identifier for the return policy. If it is not provided a random one will be generated.", "format": "uuid" }, { "name": "siteIds", "kind": "required", "type": "array", "description": "", "modelRef": "#/components/schemas/SiteId", "customType": "SiteId[]", "schema": [] }, { "name": "name", "kind": "required", "type": "string", "description": "

A human-readable name of the return policy.

" }, { "name": "groups", "kind": "required", "type": "array", "description": "", "modelRef": "#/components/schemas/ReturnPolicyGroup", "customType": "ReturnPolicyGroup[]", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "

A human-readable name of this return policy group (e.g. King Size Mattress).

" }, { "name": "triggerGroup", "kind": "required", "type": "object", "description": "

A subject that might take place as a trigger or qualifier for a return policy. It can be a

\n
    \n
  • particular SKU or the whole product.
    • \n
", "modelRef": "#/components/schemas/ReturnPolicySubject", "customType": "ReturnPolicySubject[]", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ReturnPolicyProduct", "description": "", "modelRef": "#/components/schemas/ReturnPolicyProduct", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "" }, { "name": "id", "kind": "required", "type": "string", "description": "A product ID of the product." } ] }, { "name": "ReturnPolicySku", "description": "", "modelRef": "#/components/schemas/ReturnPolicySku", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "" }, { "name": "id", "kind": "required", "type": "string", "description": "A product ID of the product this SKU belongs to." }, { "name": "skuId", "kind": "required", "type": "string", "description": "An ID of this SKU." } ] } ] }, { "name": "qualifyingGroup", "kind": "required", "type": "object", "description": "

A subject that might take place as a trigger or qualifier for a return policy. It can be a

\n
    \n
  • particular SKU or the whole product.
    • \n
", "modelRef": "#/components/schemas/ReturnPolicySubject", "customType": "ReturnPolicySubject[]", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ReturnPolicyProduct", "description": "", "modelRef": "#/components/schemas/ReturnPolicyProduct", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "" }, { "name": "id", "kind": "required", "type": "string", "description": "A product ID of the product." } ] }, { "name": "ReturnPolicySku", "description": "", "modelRef": "#/components/schemas/ReturnPolicySku", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "" }, { "name": "id", "kind": "required", "type": "string", "description": "A product ID of the product this SKU belongs to." }, { "name": "skuId", "kind": "required", "type": "string", "description": "An ID of this SKU." } ] } ] } ] }, { "name": "unqualifiedTemplate", "kind": "required", "type": "string", "description": "A message template to be populated when this return policy is triggered by cart content but the cart content does not qualify for the return policy." }, { "name": "triggeredTemplate", "kind": "required", "type": "string", "description": "A message template to be populated once this return policy is triggered by cart content." }, { "name": "activationDate", "kind": "optional", "type": "string", "description": "

An optional date determining since when the return policy is activated. If it is not provided, the activation has no lower bound.

", "example": "2021-12-01T00:00:00Z", "format": "date-time" }, { "name": "deactivationDate", "kind": "optional", "type": "string", "description": "

An optional date determining until when the return policy is activated. If it is not provided, the activation has no upper bound.

", "example": "2021-12-21T00:30:00Z", "format": "date-time" }, { "name": "archived", "kind": "optional", "type": "boolean", "description": "Determines whether the return policy is archived or not.", "default": false } ], "modelRef": "#/components/schemas/ReturnPolicy", "isExpanded": true } ] }, { "statusCode": "400", "description": "The request contained information that the server was unable to process. Appropriate errors are provided in the response body.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ValidationErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "code", "kind": "required", "type": "string", "description": "" }, { "name": "detail", "kind": "optional", "type": "string", "description": "" } ], "modelRef": "#/components/schemas/ValidationErrorResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "code", "kind": "required", "type": "string", "description": "" }, { "name": "detail", "kind": "required", "type": "string", "description": "" }, { "name": "reason", "kind": "optional", "type": "string", "description": "" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "E76vgXBjBMya-BBulQRwi", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.upstartcommerce.com/v1/return-policy \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-upstart-tenant: string' \\\n --data '{\n \"siteIds\": [],\n \"name\": \"\",\n \"groups\": [\n {\n \"name\": \"\",\n \"triggerGroup\": {\n \"type\": \"\",\n \"id\": \"\"\n },\n \"qualifyingGroup\": {\n \"type\": \"\",\n \"id\": \"\"\n }\n }\n ],\n \"triggeredTemplate\": \"\",\n \"unqualifiedTemplate\": \"\"\n }'" }, { "id": "1rCjDbS-bBRkKxSegTTWQ", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"x-upstart-tenant\", \"string\");\n\nvar raw = JSON.stringify({\n \"siteIds\": [],\n \"name\": \"\",\n \"groups\": [\n {\n \"name\": \"\",\n \"triggerGroup\": {\n \"type\": \"\",\n \"id\": \"\"\n },\n \"qualifyingGroup\": {\n \"type\": \"\",\n \"id\": \"\"\n }\n }\n ],\n \"triggeredTemplate\": \"\",\n \"unqualifiedTemplate\": \"\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/return-policy\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "HLq1RB4a1AwurK1SBC3be", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/return-policy\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-upstart-tenant\"] = \"string\"\nrequest.body = JSON.dump({\n \"siteIds\": [],\n \"name\": \"\",\n \"groups\": [\n {\n \"name\": \"\",\n \"triggerGroup\": {\n \"type\": \"\",\n \"id\": \"\"\n },\n \"qualifyingGroup\": {\n \"type\": \"\",\n \"id\": \"\"\n }\n }\n ],\n \"triggeredTemplate\": \"\",\n \"unqualifiedTemplate\": \"\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "BCXFNPSyIdnt6Z5CAT0D4", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/return-policy\"\n\npayload = json.dumps({\n \"siteIds\": [],\n \"name\": \"\",\n \"groups\": [\n {\n \"name\": \"\",\n \"triggerGroup\": {\n \"type\": \"\",\n \"id\": \"\"\n },\n \"qualifyingGroup\": {\n \"type\": \"\",\n \"id\": \"\"\n }\n }\n ],\n \"triggeredTemplate\": \"\",\n \"unqualifiedTemplate\": \"\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'x-upstart-tenant': 'string'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "E76vgXBjBMya-BBulQRwi" }, "results": { "languages": [ { "id": "RvxpJ4OjD7MEVehy_F-sp", "language": "201", "code": "// Success-return policy created.\n{\n \"id\": \"\",\n \"siteIds\": [\n \"\"\n ],\n \"name\": \"\",\n \"groups\": [\n {\n \"name\": \"\",\n \"triggerGroup\": {},\n \"qualifyingGroup\": {}\n }\n ],\n \"unqualifiedTemplate\": \"\",\n \"triggeredTemplate\": \"\",\n \"activationDate\": \"2021-12-01T00:00:00Z\",\n \"deactivationDate\": \"2021-12-21T00:30:00Z\",\n \"archived\": false\n}" }, { "id": "ittaAG0_7mtk9v5855vlu", "language": "400", "code": "// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\"\n}" }, { "id": "uh-HP__buNWlyl4M17tOC", "language": "401", "code": "// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" } ], "selectedLanguageId": "RvxpJ4OjD7MEVehy_F-sp" } }, "children": [ { "text": "" } ] }