Inventories

Several object types in the EventsAir GraphQL API have inventories, meaning they can be consumed in some way. Inventories often (but not always) have a finite limit, configured as part of an event setup.

Examples of object types that have inventories are:

• FunctionFeeType: number of spots consumed of a given function fee type.
• RegistrationDiscountCode: how many times a particular discount code was used when registering for an event.
• SponsorshipPackage: number of packages that sponsors have registered for.

The inventory may be queried for as part of these objects.

Example query for all function fee type inventories:

query ExampleQuery($limit: PositiveInt!) {
  events(limit: $limit) {
    setup {
      function {
        functions {
          name
          inventoryLimit
          feeTypes {
            name
            inventory {
              limit
              consumed
              remaining
              isPooledWithParentFunction
            }
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "events": [
      {
        "setup": {
          "function": {
            "functions": [
              {
                "name": "City Tour",
                "inventoryLimit": 100,
                "feeTypes": [
                  {
                    "name": "Member - Adult",
                    "inventory": {
                      "limit": 100,
                      "consumed": 23,
                      "remaining": 77,
                      "isPooledWithParentFunction": true
                    }
                  },
                  {
                    "name": "Non-member - Adult",
                    "inventory": {
                      "limit": 100,
                      "consumed": 23,
                      "remaining": 77,
                      "isPooledWithParentFunction": true
                    }
                  },
                  {
                    "name": "Child",
                    "inventory": {
                      "limit": null,
                      "consumed": 8,
                      "remaining": null,
                      "isPooledWithParentFunction": false
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    ]
  }
}

All inventories include the consumed, remaining, and limit fields. consumed is required, however remaining and limit may be null if the inventory has been configured to be unlimited.

Some inventories may be pooled together with a group. In the above example, isPooledWithParentFunction is true for the first two fee types, meaning there is a combined limit of 100 spots available for members and non-members in the City Tour function. If you need to see the inventory limit at the function level without having to query the fee types, you can query the inventoryLimit field on that function, as shown in the example.

Temporary Inventory Holds

It is often desirable to hold an inventory item temporarily while the user is completing another action. An example of this is holding a ticket for a contact who is signing up to a function, while they are providing their details.

Creating holds

To create a temporary inventory hold, call one of the mutations starting with createTemporaryHoldFor... and supply the relevant input fields such as the event identifier, contact identifier, and the identifier of the object type you would like to hold. If the inventory is successfully held, then the expiration of the hold is returned. In the case of a failure, including when the inventory limit has been reached, a BAD_REQUEST response is returned.

The duration of a temporary inventory hold is 20 minutes and can be extended.

Example query:

mutation ExampleHold($input: CreateTemporaryHoldForFunctionRegistrationInput!) {
  createTemporaryHoldForFunctionRegistration(input: $input) {
    expiration
  }
}

{
  "input": {
    "temporaryHoldContextId": "11111111-1111-1111-1111-111111111111",
    "contactId": "39D2B7C1-CF57-4685-A711-BF1B76D3CA4A",
    "eventId": "9EA02BE1-8E33-4888-9157-7483E91EA0B1",
    "functionFeeTypeId": "F6240828-7B4F-4D22-B325-D493BD6A4CF7",
    "paymentStatus": "PURCHASE",
    "count": 1
  }
}

Response:

{
  "data": {
    "createTemporaryHoldForFunctionRegistration": {
      "expiration": "2023-10-23T04:34:37.326Z"
    }
  }
}

Extending holds

To extend a temporary inventory hold, simply call the createTemporaryHoldFor... mutation again with the same input values prior to expiration. This will not create a new hold, but will instead extend the expiration.

Releasing holds

To release a temporary inventory hold explicitly (e.g. when a customer abandons a registration process), call the corresponding releaseTemporaryHoldFor... mutation.

Example query:

mutation ExampleRelease($input: ReleaseTemporaryHoldForFunctionRegistrationInput!) {
  releaseTemporaryHoldForFunctionRegistration(input: $input)
}

{
  "input": {
    "temporaryHoldContextId": "11111111-1111-1111-1111-111111111111",
    "contactId": "39D2B7C1-CF57-4685-A711-BF1B76D3CA4A",
    "eventId": "9EA02BE1-8E33-4888-9157-7483E91EA0B1",
    "functionFeeTypeId": "F6240828-7B4F-4D22-B325-D493BD6A4CF7"
  }
}

Response:

{
  "data": {
    "releaseTemporaryHoldForFunctionRegistration": null
  }
}

temporaryHoldContextId and automated inventory hold releases

All temporary inventory hold mutations require a temporaryHoldContextId input field to be provided. This should be set to a GUID representing the current "session" or "context" of the call. The ID achieves two objectives:

1. By providing two different values of temporaryHoldContextId, you can create two separate temporary inventory holds on an object for the same contact.

2. Some mutations such as createRegistration and createFunctionRegistration optionally accept a temporaryHoldContextId which is used to automatically release any associated temporary holds. For example if a temporary hold is placed on a function fee type, as well a hold on a discount code for that function, when createFunctionRegistration is called with the corresponding temporaryHoldContextId, then both temporary holds are released once the registration is created.