@salesforce/b2c-tooling-sdk 2.4.0 → 2.5.0

package/node_modules/@salesforce/b2c-api-schemas/scapi/pricing/shopper-gift-certificates/v1.json

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Shopper Gift Certificates",
-    "version": "1.3.0",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-gift-certificates/shopper-gift-certificates-oas-v1-public.yaml)\n\n# API Overview\n\nUse the Shopper Gift Certificates API to obtain gift certificate details.\n\n## Authentication & Authorization\n\nThe Shopper Gift Certificates API requires a JSON Web Token acquired via the Shopper Customers endpoint:\n\n```\nhttps://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login\n```\n\nYou must include the relevant scope(s) in the client ID used to generate the SLAS token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)\n\n## Customization\n\n### Custom Properties\n\nThis API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)\n\n### Hooks\n\nFor details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)\n\n## Request Details\n\n### URL Encoding\n\nIf resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)\n\n## Response Details\n\n### Personalization\n\nResponses from this API are not personalized via the Shopper Context API.\n\n### Caching\n\nResponses from this API are not cached.\n\n### Timeouts\n\nShopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)\n\n### Error Handling\n\nError responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)\n\n## Use Cases\n\n### Retrieve a Gift Certificate\n\nLook up a gift certificate by its code. The code is sent in the request body (not the URL) for security.\n\n```sh\ncurl \"https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-gift-certificates/v1/organizations/{organizationId}/gift-certificate?siteId=RefArch\" \\\n  -X POST \\\n  -H \"Authorization: Bearer {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"giftCertificateCode\": \"GIFT-1234-ABCD\" }'\n```\n\n\n### Retrieve Existing Gift Certificate Details\n\nA shopper who received a code identifying a gift certificate can use the gift certificate code to query information, such as the status or remaining balance.\n\n## Related APIs\n\n- [Gift Certificates (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates?meta=Summary) — Create and manage gift certificates.",
+    "version": "1.3.2",
     "x-api-type": "Shopper",
     "x-api-family": "Pricing"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-gift-certificates/v1",
       "variables": {
         "shortCode": {
+          "description": "An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)",
           "default": "shortCode"
         }
       }
@@ -19,56 +21,54 @@
   "paths": {
     "/organizations/{organizationId}/gift-certificate": {
       "post": {
+        "summary": "Retrieve an existing gift certificate.",
         "operationId": "getGiftCertificate",
         "parameters": [
           {
             "name": "organizationId",
             "in": "path",
+            "description": "An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).",
             "required": true,
             "style": "simple",
             "explode": false,
             "schema": {
               "$ref": "#/components/schemas/OrganizationId"
-            }
+            },
+            "example": "f_ecom_zzxy_prd"
           },
           {
             "name": "siteId",
             "in": "query",
+            "description": "The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
+            },
+            "examples": {
+              "SiteId": {
+                "value": "RefArch"
+              }
             }
           },
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "sfdc_shopper_context",
             "in": "header",
+            "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
             "required": false,
             "style": "simple",
             "explode": false,
@@ -82,6 +82,11 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/GiftCertificateRequest"
+              },
+              "examples": {
+                "Gift-Certificates": {
+                  "$ref": "#/components/examples/GetGiftCertificate"
+                }
               }
             }
           }
@@ -93,6 +98,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GiftCertificate"
+                },
+                "examples": {
+                  "CreateGiftCertificate": {
+                    "$ref": "#/components/examples/CreateGiftCertificate"
+                  }
                 }
               }
             }
@@ -103,6 +113,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "GiftCertificate404": {
+                    "$ref": "#/components/examples/GiftCertificate404"
+                  }
                 }
               }
             }
@@ -129,19 +144,26 @@
     "schemas": {
       "OrganizationId": {
         "type": "string",
+        "description": "An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).",
+        "example": "f_ecom_zzxy_prd",
         "pattern": "^f_ecom_[a-z]{4}_(prd|stg|dev|s[0-9]{2}|[0-9]{3})$"
       },
       "SiteId": {
         "type": "string",
+        "description": "The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites",
+        "example": "RefArch",
         "maxLength": 32,
         "minLength": 1
       },
       "GiftCertificateRequest": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Document representing a gift certificate request data.",
         "properties": {
           "giftCertificateCode": {
-            "type": "string"
+            "type": "string",
+            "description": "The gift certificate code.",
+            "example": "MYGIFTCERTIFICATECODE"
           }
         },
         "required": [
@@ -150,48 +172,73 @@
       },
       "GiftCertificate": {
         "type": "object",
-        "additionalProperties": {},
+        "additionalProperties": {
+          "description": "This type supports additional properties passed along with the defined properties of this API.\nTo indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`.\nThe type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.",
+          "example": "c_trackingId",
+          "title": "Additional Property Support"
+        },
+        "description": "Document representing a gift certificate.",
         "properties": {
           "amount": {
             "type": "number",
-            "format": "double"
+            "format": "double",
+            "description": "The gift certificate original amount.",
+            "example": 100
           },
           "balance": {
             "type": "number",
-            "format": "double"
+            "format": "double",
+            "description": "The gift certificate remaining balance.",
+            "example": 100
           },
           "description": {
-            "type": "string"
+            "type": "string",
+            "description": "The gift certificate description."
           },
           "enabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Is the gift certificate is enabled?",
+            "example": true
           },
           "maskedGiftCertificateCode": {
-            "type": "string"
+            "type": "string",
+            "description": "The masked gift certificate code.",
+            "example": "************FJWQ"
           },
           "merchantId": {
-            "type": "string"
+            "type": "string",
+            "description": "The merchant ID.",
+            "example": "00000001"
           },
           "message": {
-            "type": "string"
+            "type": "string",
+            "description": "The message."
           },
           "recipientEmail": {
-            "type": "string"
+            "type": "string",
+            "description": "The recipient email.",
+            "example": "p@gmail.com"
           },
           "recipientName": {
-            "type": "string"
+            "type": "string",
+            "description": "The recipient name.",
+            "example": "sampleuser"
           },
           "senderName": {
-            "type": "string"
+            "type": "string",
+            "description": "The sender name.",
+            "example": "Salesforce Support"
           },
           "status": {
             "type": "string",
+            "description": "The gift certificate status.",
             "enum": [
               "pending",
               "issued",
               "partially_redeemed",
               "redeemed"
-            ]
+            ],
+            "example": "issued"
           }
         },
         "required": [
@@ -212,17 +259,25 @@
         "properties": {
           "title": {
             "type": "string",
+            "description": "A short, human-readable summary of the problem\ntype.  It will not change from occurrence to occurrence of the \nproblem, except for purposes of localization\n",
+            "example": "You do not have enough credit",
             "maxLength": 256
           },
           "type": {
             "type": "string",
+            "description": "A URI reference [RFC3986] that identifies the\nproblem type.  This specification encourages that, when\ndereferenced, it provide human-readable documentation for the\nproblem type (e.g., using HTML [W3C.REC-html5-20141028]).  When\nthis member is not present, its value is assumed to be\n\"about:blank\". It accepts relative URIs; this means\nthat they must be resolved relative to the document's base URI, as\nper [RFC3986], Section 5.\n",
+            "example": "NotEnoughMoney",
             "maxLength": 2048
           },
           "detail": {
-            "type": "string"
+            "type": "string",
+            "description": "A human-readable explanation specific to this occurrence of the problem.",
+            "example": "Your current balance is 30, but that costs 50"
           },
           "instance": {
             "type": "string",
+            "description": "A URI reference that identifies the specific\noccurrence of the problem.  It may or may not yield further\ninformation if dereferenced.  It accepts relative URIs; this means\nthat they must be resolved relative to the document's base URI, as\nper [RFC3986], Section 5.\n",
+            "example": "/account/12345/msgs/abc",
             "maxLength": 2048
           }
         },
@@ -237,51 +292,48 @@
       "organizationId": {
         "name": "organizationId",
         "in": "path",
+        "description": "An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).",
         "required": true,
         "style": "simple",
         "explode": false,
         "schema": {
           "$ref": "#/components/schemas/OrganizationId"
-        }
+        },
+        "example": "f_ecom_zzxy_prd"
       },
       "siteId": {
         "name": "siteId",
         "in": "query",
+        "description": "The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.",
         "required": true,
         "style": "form",
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/SiteId"
+        },
+        "examples": {
+          "SiteId": {
+            "value": "RefArch"
+          }
         }
       },
       "sfdcUsid": {
         "name": "sfdc_usid",
         "in": "header",
+        "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
         "required": false,
         "style": "simple",
         "explode": false,
         "schema": {
           "type": "string",
-          "format": "uuid"
-        }
-      },
-      "sfdcDwDnt": {
-        "name": "sfdc_dw_dnt",
-        "in": "header",
-        "required": false,
-        "style": "simple",
-        "explode": false,
-        "schema": {
-          "type": "string",
-          "enum": [
-            "0",
-            "1"
-          ]
+          "format": "uuid",
+          "example": "550e8400-e29b-41d4-a716-446655440000"
         }
       },
       "sfdcShopperContext": {
         "name": "sfdc_shopper_context",
         "in": "header",
+        "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
         "required": false,
         "style": "simple",
         "explode": false,
@@ -290,9 +342,39 @@
         }
       }
     },
+    "examples": {
+      "GetGiftCertificate": {
+        "value": {
+          "giftCertificateCode": "MYGIFTCERTIFICATECODE"
+        }
+      },
+      "CreateGiftCertificate": {
+        "summary": "A newly issued gift certificate with full balance.",
+        "value": {
+          "amount": 100,
+          "balance": 100,
+          "enabled": true,
+          "maskedGiftCertificateCode": "************FJWQ",
+          "merchantId": "00000001",
+          "recipientEmail": "jane.doe@example.com",
+          "recipientName": "Jane Doe",
+          "senderName": "John Smith",
+          "status": "issued",
+          "description": "Happy Birthday!"
+        }
+      },
+      "GiftCertificate404": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
+          "title": "Gift Certificate Not Found Exception",
+          "detail": "The gift certificate with the provided code could not be retrieved."
+        }
+      }
+    },
     "securitySchemes": {
       "ShopperToken": {
         "type": "oauth2",
+        "description": "ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. \nFor a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).\nA shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications.\nThe `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.\n",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token",
@@ -311,6 +393,7 @@
       },
       "ShopperClientContextToken": {
         "type": "oauth2",
+        "description": "ShopperClientContextToken is a separate security scheme used to track and validate client context information.\nIt is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows.\nFor authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).\nThis token allows access to Shopper API endpoints for guest shoppers only.\n",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client_context",