---
schema_version: "1"
id: ba082987f1c5a861eed544b5e2aae70eb25897f14e88a72fb95916941ab8257f
title: Promotion Code Validation SPI
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/promotion-code-validation-spi.md
canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/promotion-code-validation-spi
source_site: developer.salesforce.com
content_type: documentation
content_hash: 96936e43024b251c1e3ad6691c67ef3a553222d6955f19f1678d89527245ae35
products:
  - Point of Sale for Developers
  - Salesforce APIs
---
Promotion Code Validation SPI

# Promotion Code Validation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-code-validation-spi/promotion-code-validation-spi-oas-public.yaml)

Merchant SPI to validate promotion codes from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in POS CMS for the POS to use when applying promotion codes.

**Version:** 2.3.4

## Tags

### Promotion Code Validation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-code-validation-spi/promotion-code-validation-spi-oas-public.yaml)

Merchant SPI to validate promotion codes from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in POS CMS for the POS to use when applying promotion codes.

## Operations

### POST Validate promotion code.

`POST /merchant/spi/sample/endpoint/sa/promotionCodeValidation`

Operation ID: `validatePromoCode`. Tags: Promotion Code Validation SPI.

Validate a provided promotion code by checking its validity and returning the associated promotion ID. If the promotion code is valid, the response returns the corresponding promotion ID. If the promotion code is invalid, the response returns an empty promotion ID. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SUPC_PROMOTION_CODE_VALIDATION`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `PromoCodeValidationRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PromoCodeValidationResponse`.
    

## Schemas

### PromoCodeValidationRequest

*   `promotionCode` (_string_, required) Promotion code to validate.

### PromoCodeValidationResponse

*   `promotionId` (_string_, nullable) If the promotion code is valid, return the promotion ID; otherwise, return empty.
*   `merchantPromotionId` (_string_, nullable) If the promotion code is valid, return the merchant's identifier for the relevant promotion; otherwise, return empty. This is the merchantPromotionId which should have been sent/used during promotion creation/updates.