# Vend\PromotionsApi

Promotion operations

All URIs are relative to https://example.retail.lightspeed.app/api/2026-07, except if the operation defines another base path.

| Method | HTTP request | Description |
| ------------- | ------------- | ------------- |
| [**applyDiscount()**](PromotionsApi.md#applyDiscount) | **POST** /discount | Apply discounts to a sale object |
| [**createPromotion()**](PromotionsApi.md#createPromotion) | **POST** /promotions | Create a promotion |
| [**getPromotionByID()**](PromotionsApi.md#getPromotionByID) | **GET** /promotions/{promotion_id} | Get a promotion by ID |
| [**getPromotionProducts()**](PromotionsApi.md#getPromotionProducts) | **GET** /promotions/{promotion_id}/products | Get products for a promotion |
| [**getPromotionPromoCodes()**](PromotionsApi.md#getPromotionPromoCodes) | **GET** /promotions/{promotion_id}/promocodes | Get the promo codes for a promotion |
| [**listPromotions()**](PromotionsApi.md#listPromotions) | **GET** /promotions | List promotions |
| [**searchPromotions()**](PromotionsApi.md#searchPromotions) | **GET** /promotions/search | Search promotions |
| [**updatePromotion()**](PromotionsApi.md#updatePromotion) | **PUT** /promotions/{promotion_id} | Update a promotion |


## `applyDiscount()`

```php
applyDiscount($discount_param): \Vend\Model\DiscountResponse
```

Apply discounts to a sale object

This will find the best possible promotion to a sale, apply it and return the sale and the discount.   * Despite its `POST` method, this endpoint does not modify any server-side state.  * It is the caller's responsibility to pass along the full details of the sale, including all customer information and product information (product type, tags, etc.).   🔒 Requires: `promotions:read` `outlets:read` scopes

### Example

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer (JWT) authorization: bearerAuth
$config = Vend\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Vend\Api\PromotionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$discount_param = new \Vend\Model\DiscountParam(); // \Vend\Model\DiscountParam

try {
    $result = $apiInstance->applyDiscount($discount_param);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PromotionsApi->applyDiscount: ', $e->getMessage(), PHP_EOL;
}
```

### Parameters

| Name | Type | Description  | Notes |
| ------------- | ------------- | ------------- | ------------- |
| **discount_param** | [**\Vend\Model\DiscountParam**](../Model/DiscountParam.md)|  | |

### Return type

[**\Vend\Model\DiscountResponse**](../Model/DiscountResponse.md)

### Authorization

[bearerAuth](../../README.md#bearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`

[[Back to top]](#) [[Back to API list]](../../README.md#endpoints)
[[Back to Model list]](../../README.md#models)
[[Back to README]](../../README.md)

## `createPromotion()`

```php
createPromotion($promotion): \Vend\Model\PromotionResponse
```

Create a promotion

This endpoint creates a new promotion.  It responds with the newly-created promotion, including the promotion's ID.  🔒 Requires: `promotions:write` scope

### Example

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer (JWT) authorization: bearerAuth
$config = Vend\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Vend\Api\PromotionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$promotion = new \Vend\Model\Promotion(); // \Vend\Model\Promotion

try {
    $result = $apiInstance->createPromotion($promotion);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PromotionsApi->createPromotion: ', $e->getMessage(), PHP_EOL;
}
```

### Parameters

| Name | Type | Description  | Notes |
| ------------- | ------------- | ------------- | ------------- |
| **promotion** | [**\Vend\Model\Promotion**](../Model/Promotion.md)|  | |

### Return type

[**\Vend\Model\PromotionResponse**](../Model/PromotionResponse.md)

### Authorization

[bearerAuth](../../README.md#bearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`

[[Back to top]](#) [[Back to API list]](../../README.md#endpoints)
[[Back to Model list]](../../README.md#models)
[[Back to README]](../../README.md)

## `getPromotionByID()`

```php
getPromotionByID($promotion_id): \Vend\Model\GetPromotionByID200Response
```

Get a promotion by ID

This will retrieve a single promotion using the given ID.  🔒 Requires: `promotions:read` scope

### Example

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer (JWT) authorization: bearerAuth
$config = Vend\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Vend\Api\PromotionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$promotion_id = 56; // int | The promotion id

try {
    $result = $apiInstance->getPromotionByID($promotion_id);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PromotionsApi->getPromotionByID: ', $e->getMessage(), PHP_EOL;
}
```

### Parameters

| Name | Type | Description  | Notes |
| ------------- | ------------- | ------------- | ------------- |
| **promotion_id** | **int**| The promotion id | |

### Return type

[**\Vend\Model\GetPromotionByID200Response**](../Model/GetPromotionByID200Response.md)

### Authorization

[bearerAuth](../../README.md#bearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`

[[Back to top]](#) [[Back to API list]](../../README.md#endpoints)
[[Back to Model list]](../../README.md#models)
[[Back to README]](../../README.md)

## `getPromotionProducts()`

```php
getPromotionProducts($promotion_id, $page_size, $offset, $name): \Vend\Model\PromotionProductsResponse
```

Get products for a promotion

Get a list of products applicable for this promotion, and their discount price.  It takes in `page_size`, `offset` and `name` (use for searching product by product name) as query parameters.  The endpoint returns:  * a list of products with discount for the condition product set, and  * another list for the action product sets.  🔒 Requires: `promotions:read` `products:read` scopes

### Example

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer (JWT) authorization: bearerAuth
$config = Vend\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Vend\Api\PromotionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$promotion_id = 56; // int | The promotion id
$page_size = 56; // int
$offset = 56; // int
$name = 'name_example'; // string | Filter products by product name.

try {
    $result = $apiInstance->getPromotionProducts($promotion_id, $page_size, $offset, $name);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PromotionsApi->getPromotionProducts: ', $e->getMessage(), PHP_EOL;
}
```

### Parameters

| Name | Type | Description  | Notes |
| ------------- | ------------- | ------------- | ------------- |
| **promotion_id** | **int**| The promotion id | |
| **page_size** | **int**|  | [optional] |
| **offset** | **int**|  | [optional] |
| **name** | **string**| Filter products by product name. | [optional] |

### Return type

[**\Vend\Model\PromotionProductsResponse**](../Model/PromotionProductsResponse.md)

### Authorization

[bearerAuth](../../README.md#bearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`

[[Back to top]](#) [[Back to API list]](../../README.md#endpoints)
[[Back to Model list]](../../README.md#models)
[[Back to README]](../../README.md)

## `getPromotionPromoCodes()`

```php
getPromotionPromoCodes($promotion_id): \Vend\Model\PromotionPromoCodesResponse
```

Get the promo codes for a promotion

Get the promo codes associated with this promotion.  🔒 Requires: `promotions:read` scope

### Example

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer (JWT) authorization: bearerAuth
$config = Vend\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Vend\Api\PromotionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$promotion_id = 'promotion_id_example'; // string | The promotion id

try {
    $result = $apiInstance->getPromotionPromoCodes($promotion_id);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PromotionsApi->getPromotionPromoCodes: ', $e->getMessage(), PHP_EOL;
}
```

### Parameters

| Name | Type | Description  | Notes |
| ------------- | ------------- | ------------- | ------------- |
| **promotion_id** | **string**| The promotion id | |

### Return type

[**\Vend\Model\PromotionPromoCodesResponse**](../Model/PromotionPromoCodesResponse.md)

### Authorization

[bearerAuth](../../README.md#bearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`

[[Back to top]](#) [[Back to API list]](../../README.md#endpoints)
[[Back to Model list]](../../README.md#models)
[[Back to README]](../../README.md)

## `listPromotions()`

```php
listPromotions($end_time_to, $end_time_from, $page_size): \Vend\Model\PromotionCollection
```

List promotions

This endpoint lists all promotions for a retailer.  There are optional query parameters that allow filtering promotions. They can't be combined:   - `end_time_from` - only show promotions that have end\\_time after or equal to this time  - `end_time_to` - only show promotions that have end\\_time before this time  For example. the time format for end\\_time\\_from and end\\_time\\_to are: `2047-06-21T13:00:00`  🔒 Requires: `promotions:read` scope

### Example

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer (JWT) authorization: bearerAuth
$config = Vend\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Vend\Api\PromotionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$end_time_to = 'end_time_to_example'; // string | Upper limit for the promotion end date as UTC timestamp. Format: `2020-08-08T12:00:00Z`.
$end_time_from = 'end_time_from_example'; // string | Lower limit for the promotion end date as UTC timestamp. Format: `2020-08-08T12:00:00Z`.
$page_size = 56; // int | The maximum number of items to be returned in the response.

try {
    $result = $apiInstance->listPromotions($end_time_to, $end_time_from, $page_size);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PromotionsApi->listPromotions: ', $e->getMessage(), PHP_EOL;
}
```

### Parameters

| Name | Type | Description  | Notes |
| ------------- | ------------- | ------------- | ------------- |
| **end_time_to** | **string**| Upper limit for the promotion end date as UTC timestamp. Format: &#x60;2020-08-08T12:00:00Z&#x60;. | [optional] |
| **end_time_from** | **string**| Lower limit for the promotion end date as UTC timestamp. Format: &#x60;2020-08-08T12:00:00Z&#x60;. | [optional] |
| **page_size** | **int**| The maximum number of items to be returned in the response. | [optional] |

### Return type

[**\Vend\Model\PromotionCollection**](../Model/PromotionCollection.md)

### Authorization

[bearerAuth](../../README.md#bearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`

[[Back to top]](#) [[Back to API list]](../../README.md#endpoints)
[[Back to Model list]](../../README.md#models)
[[Back to README]](../../README.md)

## `searchPromotions()`

```php
searchPromotions($scope, $name, $start_time, $end_time, $outlet_id, $order_by, $direction, $offset, $page_size): \Vend\Model\PromotionCollection
```

Search promotions

This endpoint can be used to find promotions matching specific criteria.  🔒 Requires: `promotions:read` scope

### Example

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer (JWT) authorization: bearerAuth
$config = Vend\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Vend\Api\PromotionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$scope = 'all'; // string | Scope of the search
$name = choco; // string | Part of promotion's name being searched
$start_time = 2022-08-29T9:57:52; // string | Only show promotions that have a start time after or equal to this
$end_time = 2023-08-29T9:57:52; // string | Only show promotions that have an end time before or equal to this
$outlet_id = array('outlet_id_example'); // string[] | Only show promotions linked to one or many of the outlets specified here
$order_by = 'name'; // string | Sort the result by this field
$direction = 'desc'; // string | Sort direction
$offset = 1; // int | Offset
$page_size = 1000; // int | Number of results per page

try {
    $result = $apiInstance->searchPromotions($scope, $name, $start_time, $end_time, $outlet_id, $order_by, $direction, $offset, $page_size);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PromotionsApi->searchPromotions: ', $e->getMessage(), PHP_EOL;
}
```

### Parameters

| Name | Type | Description  | Notes |
| ------------- | ------------- | ------------- | ------------- |
| **scope** | **string**| Scope of the search | [optional] [default to &#39;all&#39;] |
| **name** | **string**| Part of promotion&#39;s name being searched | [optional] |
| **start_time** | **string**| Only show promotions that have a start time after or equal to this | [optional] |
| **end_time** | **string**| Only show promotions that have an end time before or equal to this | [optional] |
| **outlet_id** | [**string[]**](../Model/string.md)| Only show promotions linked to one or many of the outlets specified here | [optional] |
| **order_by** | **string**| Sort the result by this field | [optional] [default to &#39;name&#39;] |
| **direction** | **string**| Sort direction | [optional] [default to &#39;desc&#39;] |
| **offset** | **int**| Offset | [optional] [default to 1] |
| **page_size** | **int**| Number of results per page | [optional] [default to 1000] |

### Return type

[**\Vend\Model\PromotionCollection**](../Model/PromotionCollection.md)

### Authorization

[bearerAuth](../../README.md#bearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`

[[Back to top]](#) [[Back to API list]](../../README.md#endpoints)
[[Back to Model list]](../../README.md#models)
[[Back to README]](../../README.md)

## `updatePromotion()`

```php
updatePromotion($promotion_id, $promotion): \Vend\Model\PromotionResponse
```

Update a promotion

This endpoint updates an existing promotion by ID.   * All of a promotion's fields except its id may be updated.  * There are no partial updates.  * All fields must be specified in the update.  * The response contains the updated promotion object.  🔒 Requires: `promotions:write` scope

### Example

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer (JWT) authorization: bearerAuth
$config = Vend\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Vend\Api\PromotionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$promotion_id = 'promotion_id_example'; // string | The promotion id
$promotion = new \Vend\Model\Promotion(); // \Vend\Model\Promotion

try {
    $result = $apiInstance->updatePromotion($promotion_id, $promotion);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PromotionsApi->updatePromotion: ', $e->getMessage(), PHP_EOL;
}
```

### Parameters

| Name | Type | Description  | Notes |
| ------------- | ------------- | ------------- | ------------- |
| **promotion_id** | **string**| The promotion id | |
| **promotion** | [**\Vend\Model\Promotion**](../Model/Promotion.md)|  | |

### Return type

[**\Vend\Model\PromotionResponse**](../Model/PromotionResponse.md)

### Authorization

[bearerAuth](../../README.md#bearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`

[[Back to top]](#) [[Back to API list]](../../README.md#endpoints)
[[Back to Model list]](../../README.md#models)
[[Back to README]](../../README.md)
