Creating a card

To create an order in Toggle, make a mutation request to createOrder. The typical use cases for this journey are;

• Toggle fulfils

• Partner generates a gift card, and fulfils to the guest

Toggle fulfils

If you would like Toggle to fulfil the email to the guest, then you will need to ensure that;

• fulfilment_method_id = 1

• fulfilment_email = guest to receive gift card

mutation CreateOrder {
    createOrder(
        account_id: 1
        currency: "GBP"
        merchant_id: 24
        group_fulfilment: false
        auto_fulfil_group_fulfilment: true
        merchant_transaction_reference: "912321-2139433213-12323421_26062021"
        total: 0
        sales_channel_id: 3
        note: "Guest had a bad experience, £10 offered"
        order_items: [
            {
                product_id: 3532
                custom_price_modifier_value: 5000
                fulfilment_method_id: 1
                generate_card_reference: true
                fulfilment_email: "[email protected]"
                discounts: [{
                    discount_type_id: 1
                    value: 5000
                }]
            }
        ]
    ) {
    id,
    LineItems{
        id
        Card{
            id
            card_reference
            pin
            balance
            expiry_time
            card_alias_card_reference
            product_name
        }
    }
  }
}

Partner fulfils

If you would like to fulfil the email to the guest, then you will need to ensure that;

• fulfilment_method_id = 8

The card reference can be specified to return in the response, which can then be passed onto the guest.

mutation CreateOrder {
    createOrder(
        account_id: 1
        currency: "GBP"
        merchant_id: 24
        group_fulfilment: false
        auto_fulfil_group_fulfilment: true
        merchant_transaction_reference: "912321-2139433213-12323421_26062021"
        total: 0
        sales_channel_id: 3
        note: "Guest had a bad experience, £10 offered"
        order_items: [
            {
                product_id: 3532
                custom_price_modifier_value: 5000
                fulfilment_method_id: 8
                generate_card_reference: true
                discounts: [{
                    discount_type_id: 1
                    value: 5000
                }]
            }
        ]
    ) {
    id,
    LineItems{
        id
        Card{
            id
            card_reference
            pin
            balance
            expiry_time
            card_alias_card_reference
            product_name
        }
    }
  }
}

What contact details should I use?

The receipt_contact details are the "purchaser" of the card. So for automated guest gratuity cards, you could either hard-code these to a system level address or you could use the currently logged in user to your own platform, if you have such a thing or... you can leave the receipt_contact details out of your mutation. If the receipt_contact is added, and the account has 'Send receipt emails' enabled - then this email address will receive confirmation whenever an order is added against them (note, this is just a receipt and not the actual gift card)

What merchant ID to I use?

Merchant IDs are issued to approved partner integrations for auditing and reporting purposes. If you have not been issued with a merchant_id, you may remove this field from your query.

What product ID should I use?

All orders in Toggle are linked to a product. This would enable you to create a menu of product options to choose from when selling a gift card or experience.

To retrieve a list of products for an account:

APi query

query($account_id:Int!) {
  Products(account_id:$account_id) {
    id
    name
  }
}

Variables

{
  "data": {
    "Products": [
      {
        "id": 244,
        "name": "In-Store Gift"
      },
      {
        "id": 245,
        "name": "Summer Promotion"
      }
    ]
  }
}

Alternatively, we do have a default product on every account which you can use if you wish to simply sell a single gift card product type and avoid the extra overhead of creating a menu of product options to choose from.

To retrieve the default product ID, use the same query as above and find a product called "In-store Gift". This Product ID will be unique per customer/client account, but you only need to retrieve and configure this id a single time as it will not change for an account once that account exists.

Price modifier vs custom price modifiers

The price_modifier_id relates to the particular price option for this card. e.g. a pre-defined list of denominations.

Products can also be set to allow a "custom price modifier" on a product-by-product basis. In such cases, you can pass in the value of the card using:

"custom_price_modifier_value": 2500

instead of using a price_modifier_id.

Total vs discounts

For Guest Gratuity cards, the total would always typically be 0 as there is nothing to pay.

For the discount, this is passed in with a discount_type_id and value. A discount type of 1 is a general-use FOC type, though we also have other types available. For example 3 is for discounts for promotions.

These different configuration variables are all to designed to aid book-keepers with reporting on card sales and discounts.

What does auto_fulfil_group_fulfilment do?

This variable automatically marks your order as 'fulfilled' in Toggle (e.g. sent and dispatched). If, for some reason, you wanted to leave an order as open, and mark as fulfilled later, you could do this with some subsequent API calls. However, for your use-case, we recommend using this to automatically close off all orders you create as fulfilled.