# Mutations / Promotions

# Promotions

**Mutation**
## activatePromotion — Returns [Promotion](/documentation/Objects/Promotions#Promotion)

**Scopes required:** create_advance_promotions

| Arguments | Type | Description |
| --- | --- | --- |
| id | [ID!](/documentation/Types/UUID#UUID) | The UUID of the promotion being activated |

**Example Mutation**

```graphql
mutation ActivatePromotion($id: ID!) {
    activatePromotion(id: $id) {
        id,
        mdbId,
        mdbSyncing,
        clientId,
        name
    }
}

# Example variables
{
    "id": "<ID>"
}
```

**Mutation**
## clonePromotion — Returns [Promotion](/documentation/Objects/Promotions#Promotion)

**Scopes required:** see_promotions, create_advance_promotions

| Arguments | Type | Description |
| --- | --- | --- |
| id | [ID!](/documentation/Types/UUID#UUID) | The UUID of the promotion to clone |

**Example Mutation**

```graphql
mutation ClonePromotion($id: ID!) {
    clonePromotion(id: $id) {
        id,
        mdbId,
        mdbSyncing,
        clientId,
        name
    }
}

# Example variables
{
    "id": "<ID>"
}
```

**Mutation**
## createPromotion — Returns [Promotion](/documentation/Objects/Promotions#Promotion)

**Scopes required:** create_advance_promotions

> <p>
> Express promotions require the criteria to be set up differently.
> All the express promotion's `criteria` must have only one item on it and cannot be excluded.
> The `criteria` also can only have `type` set to either `SELL_TOTAL`,
> `DISCOUNT_PERCENTAGE` or `DISCOUNT_TOTAL_AMOUNT`.
> When `type` is set to `SELL_TOTAL` the item in the criteria can only be product or family.
> </p>

| Arguments | Type | Description |
| --- | --- | --- |
| name | *String!* | The name of the promotion |
| start | [DateTime](/documentation/Types/Date-Time#DateTime) | The start date of the promotion, when the field is `null` the promotion has no start date. If schedule is set then these fields will be ignored |
| end | [DateTime](/documentation/Types/Date-Time#DateTime) | The end date of the promotion, when the field is `null` the promotion has no end date. If schedule is set then these fields will be ignored |
| promotionCategory | [ID](/documentation/Types/UUID#UUID) | The UUID of the promotion category for the promotion |
| customerGroups | [[ID]](/documentation/Types/UUID#UUID) | The UUIDs of the customer groups that the promotion is available to. Leave unset for the promotion to be available to all customers |
| outlets | [[ID]](/documentation/Types/UUID#UUID) | The outlets that the promotion runs on, if not provided, this will add to all Outlets |
| express | *Boolean* | Whether the promotion is an express promotion |
| mixCriteria | *Boolean* | Whether the criteria should mix together as if they were a single criteria |
| saleMaxApplicationCount | *Int* | The maximum number of times this promotion can be applied to a single sale, if null then it's unlimited. This must be null for express promotions |
| criteria | [[PromotionCriteriaInput]](/documentation/Inputs/Promotions#PromotionCriteriaInput) | The criteria for the promotion |
| schedule | [PromotionScheduleInput](/documentation/Inputs/Promotions#PromotionScheduleInput) | The schedule for how often this promotion reoccurs. If set, this overrides the provided start and end values |
| active | *Boolean* | Whether the promotion is active |
| clientId | *String* | Your ID of the promotion, this is not displayed anywhere and only available through the API |
| activatedBy | *String* | If provided, this can be used to toggle the promotion on / off with the `Sell Screen Promotion Applicable` event via the Embedded API |

**Example Mutation**

```graphql
mutation CreatePromotion($name: String!) {
    createPromotion(name: $name) {
        id,
        mdbId,
        mdbSyncing,
        clientId,
        name
    }
}

# Example variables
{
    "name": "<NAME>"
}
```

**Mutation**
## deactivatePromotion — Returns [Promotion](/documentation/Objects/Promotions#Promotion)

**Scopes required:** delete_promotions

| Arguments | Type | Description |
| --- | --- | --- |
| id | [ID!](/documentation/Types/UUID#UUID) | The UUID of the promotion being deleted |

**Example Mutation**

```graphql
mutation DeactivatePromotion($id: ID!) {
    deactivatePromotion(id: $id) {
        id,
        mdbId,
        mdbSyncing,
        clientId,
        name
    }
}

# Example variables
{
    "id": "<ID>"
}
```

**Mutation**
## deletePromotion — Returns [Promotion](/documentation/Objects/Promotions#Promotion)

**Scopes required:** delete_promotions

| Arguments | Type | Description |
| --- | --- | --- |
| id | [ID!](/documentation/Types/UUID#UUID) | The UUID of the promotion being deleted |

**Example Mutation**

```graphql
mutation DeletePromotion($id: ID!) {
    deletePromotion(id: $id) {
        id,
        mdbId,
        mdbSyncing,
        clientId,
        name
    }
}

# Example variables
{
    "id": "<ID>"
}
```

**Mutation**
## updatePromotion — Returns [Promotion](/documentation/Objects/Promotions#Promotion)

**Scopes required:** edit_advance_promotions

> <p>Express promotions require the criteria to be set up differently.
> All the express promotion's `criteria` must have only one item on it and cannot be excluded.
> The `criteria` also can only have `type` set to either `SELL_TOTAL`,
> `DISCOUNT_PERCENTAGE` or `DISCOUNT_TOTAL_AMOUNT`. When `type` is set to
> `SELL_TOTAL` the item in the criteria can only be product or family.</p>

| Arguments | Type | Description |
| --- | --- | --- |
| id | [ID!](/documentation/Types/UUID#UUID) | The UUID of the promotion being updated |
| name | *String* | The name of the promotion |
| start | [DateTime](/documentation/Types/Date-Time#DateTime) | The start date of the promotion, when the field is `null` the promotion has no start date. If schedule is set these fields will be ignored |
| end | [DateTime](/documentation/Types/Date-Time#DateTime) | The end date of the promotion, when the field is `null` the promotion has no end date. If schedule is set these fields will be ignored |
| promotionCategory | [ID](/documentation/Types/UUID#UUID) | The UUID of the promotion category for the promotion |
| customerGroups | [[ID]](/documentation/Types/UUID#UUID) | The UUIDs of the customer groups that the promotion is available to. Leave unset for the promotion to be available to all customers |
| outlets | [[ID]](/documentation/Types/UUID#UUID) | The outlets that the promotion runs on |
| express | *Boolean* | Whether the promotion is an express promotion |
| mixCriteria | *Boolean* | Whether the criteria should mix together as if they were a single criteria |
| saleMaxApplicationCount | *Int* | The maximum number of times this promotion can be applied to a single sale, if null then it's unlimited. This must be null for express promotions |
| criteria | [[PromotionCriteriaInput]](/documentation/Inputs/Promotions#PromotionCriteriaInput) | The criteria for the promotion |
| schedule | [PromotionScheduleInput](/documentation/Inputs/Promotions#PromotionScheduleInput) | The schedule for how often this promotion reoccurs. If set, this overrides the provided start and end values |
| active | *Boolean* | Whether the promotion is active |
| clientId | *String* | Your ID of the promotion, this is not displayed anywhere and only available through the API |
| activatedBy | *String* | If provided, this can be used to toggle the promotion on / off with the `Sell Screen Promotion Applicable` event via the Embedded API |

**Example Mutation**

```graphql
mutation UpdatePromotion($id: ID!) {
    updatePromotion(id: $id) {
        id,
        mdbId,
        mdbSyncing,
        clientId,
        name
    }
}

# Example variables
{
    "id": "<ID>"
}
```