Using the GraphQL APIs

Important

The GraphQL API for Product Associations is currently in Preview status for customers on the AWS-US cluster. For more information, see GraphQL API policy.

Step 1 - Create Price Definition - GraphQL API

Authentication

Price Definition is located in the pricing microservice
Credentials are OAuth2 Client Credentials

A. Single Subscription, Recurring, USER unit only, Unit Range: 1-infinity, New Developer Price and Markup Price

Price Definition Mutation Request Example

mutation createPriceDefinition($input: CreatePriceDefinitionInput!) {
  createPriceDefinition(input: $input) {
    priceDefinition {
      id
      type
      pricingPlanId
      editionId
      productId
      items {
        pricingUnit
        costType
        costTypeCategory
        customMeteredUsage
        sources {
          priceType
          pricingStrategy
          priceRanges {
            minUnits
            maxUnits
            price
          }
        }
      }
      externalReferences {
        ref
        type
      }
    }
  }
}

Price Definition Mutation Variables Example

{
  "input": {
    "pricingPlanId": "05ca2a6c-64fa-11ed-9022-0242ac120002",
    "editionId": "7bcdae96-64fa-11ed-9022-0242ac120002",
    "productId": "818ead6c-64fa-11ed-9022-0242ac120002",
    "type": "BASE",
    "items": [
      {
        "costType": "RECURRING_PER_UNIT",
        "costTypeCategory": "RECURRING",
        "customMeteredUsage": false,
        "pricingUnit": "USER",
        "sources": [
          {
            "priceType": "BASE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": 10
              }
            ]
          },
          {
            "priceType": "MARKETPLACE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": 11.15
              }
            ]
          }
        ]
      }
    ],
    "externalReferences": [
      {
        "ref": "1234",
        "type": "PURCHASE_ORDER"
      },
      {
        "ref": "90248ebe-64fa-11ed-9022-0242ac120002",
        "type": "SUBSCRIPTION"
      }
    ]
  }
}

Price Definition Mutation Variables Template

{
  "input": {
    "pricingPlanId": "<pricing_plan_uuid>",
    "editionId": "<edition_uuid>",
    "productId": "<product_uuid>",
    "type": "BASE",
    "items": [
      {
        "costType": "RECURRING_PER_UNIT",
        "costTypeCategory": "RECURRING",
        "customMeteredUsage": false,
        "pricingUnit": "USER",
        "sources": [
          {
            "priceType": "BASE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": <new_developer_base_price>
              }
            ]
          },
          {
            "priceType": "MARKETPLACE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": <new_marketplace_price>
              }
            ]
          }
        ]
      }
    ],
    "externalReferences": [
      {
        "ref": "<purchase_order_id>",
        "type": "PURCHASE_ORDER"
      },
      {
        "ref": "<subscription_uuid>",
        "type": "SUBSCRIPTION"
      }
    ]
  }
}

Price Definition Mutation Response

{
  "data": {
    "createPriceDefinition": {
      "priceDefinition": {
        "id": "615c9d56551fa24714c8c3c6",
        "pricingPlanId": "05ca2a6c-64fa-11ed-9022-0242ac120002",
        "editionId": "7bcdae96-64fa-11ed-9022-0242ac120002",
        "productId": "818ead6c-64fa-11ed-9022-0242ac120002",
        "type": "BASE",
        "items": [
          {
            "costType": "RECURRING_PER_UNIT",
            "costTypeCategory": "RECURRING",
            "customMeteredUsage": false,
            "pricingUnit": "USER",
            "sources": [
              {
                "priceType": "BASE_PRICE",
                "pricingStrategy": "UNIT",
                "priceRanges": [
                  {
                    "minUnits": 1,
                    "price": 10
                  }
                ]
              },
              {
                "priceType": "MARKETPLACE_PRICE",
                "pricingStrategy": "UNIT",
                "priceRanges": [
                  {
                    "minUnits": 1,
                    "price": 11.15
                  }
                ]
              }
            ]
          }
        ],
        "externalReferences": [
          {
            "ref": "1234",
            "type": "PURCHASE_ORDER"
          },
          {
            "ref": "90248ebe-64fa-11ed-9022-0242ac120002",
            "type": "SUBSCRIPTION"
          }
        ]
      }
    }
  }
}

B. Single Subscription, Recurring, USER unit only, Unit Ranges: Tiered 1-10 & 10-infinity, New Developer Price and Markup Price

Price Definition Mutation Request Example

mutation createPriceDefinition($input: CreatePriceDefinitionInput!) {
  createPriceDefinition(input: $input) {
    priceDefinition {
      id
      type
      pricingPlanId
      editionId
      productId
      items {
        pricingUnit
        costType
        costTypeCategory
        customMeteredUsage
        sources {
          priceType
          pricingStrategy
          priceRanges {
            minUnits
            maxUnits
            price
          }
        }
      }
      externalReferences {
        ref
        type
      }
    }
  }
}

Price Definition Mutation Variables Example

{
  "input": {
    "pricingPlanId": "05ca2a6c-64fa-11ed-9022-0242ac120002",
    "editionId": "7bcdae96-64fa-11ed-9022-0242ac120002",
    "productId": "818ead6c-64fa-11ed-9022-0242ac120002",
    "type": "BASE",
    "items": [
      {
        "costType": "RECURRING_PER_UNIT",
        "costTypeCategory": "RECURRING",
        "customMeteredUsage": false,
        "pricingUnit": "USER",
        "sources": [
          {
            "priceType": "BASE_PRICE",
            "pricingStrategy": "TIERED",
            "priceRanges": [
              {
                "minUnits": 1,
                "maxUnits": 10,
                "price": 10
              },
              {
                "minUnits": 10,
                "price": 9
              }
            ]
          },
          {
            "priceType": "MARKETPLACE_PRICE",
            "pricingStrategy": "TIERED",
            "priceRanges": [
              {
                "minUnits": 1,
                "maxUnits": 10,
                "price": 11.5
              },
              {
                "minUnits": 10,
                "price": 8.23
              }
            ]
          }
        ]
      }
    ],
    "externalReferences": [
      {
        "ref": "1234",
        "type": "PURCHASE_ORDER"
      },
      {
        "ref": "90248ebe-64fa-11ed-9022-0242ac120002",
        "type": "SUBSCRIPTION"
      }
    ]
  }
}

Price Definition Mutation Variables Template

{
  "input": {
    "pricingPlanId": "<pricing_plan_uuid>",
    "editionId": "<edition_uuid>",
    "productId": "<product_uuid>",
    "type": "BASE",
    "items": [
      {
        "costType": "RECURRING_PER_UNIT",
        "costTypeCategory": "RECURRING",
        "customMeteredUsage": false,
        "pricingUnit": "USER",
        "sources": [
          {
            "priceType": "BASE_PRICE",
            "pricingStrategy": "TIERED",
            "priceRanges": [
              {
                "minUnits": <min_of_range_1>,
                "maxUnits": <max_of_range_1>,
                "price": <new_developer_base_price>
              },
              {
                "minUnits": <min_of_range_2>,
                "price": <new_developer_base_price>
              }
            ]
          },
          {
            "priceType": "MARKETPLACE_PRICE",
            "pricingStrategy": "TIERED",
            "priceRanges": [
              {
                "minUnits": <min_of_range_1>,
                "maxUnits": <max_of_range_1>,
                "price": <new_marketplace_price>
              },
              {
                "minUnits": <min_of_range_2>,
                "price": <new_marketplace_price>
              }
            ]
          }
        ]
      }
    ],
    "externalReferences": [
      {
        "ref": "<purchase_order_id>",
        "type": "PURCHASE_ORDER"
      },
      {
        "ref": "<subscription_uuid>",
        "type": "SUBSCRIPTION"
      }
    ]
  }
}

Price Definition Mutation Response

{
  "data": {
    "createPriceDefinition": {
      "priceDefinition": {
        "id": "615c9d56551fa24714c8c3c6",
        "pricingPlanId": "05ca2a6c-64fa-11ed-9022-0242ac120002",
        "editionId": "7bcdae96-64fa-11ed-9022-0242ac120002",
        "productId": "818ead6c-64fa-11ed-9022-0242ac120002",
        "type": "BASE",
        "items": [
          {
            "costType": "RECURRING_PER_UNIT",
            "costTypeCategory": "RECURRING",
            "customMeteredUsage": false,
            "pricingUnit": "USER",
            "sources": [
              {
                "priceType": "BASE_PRICE",
                "pricingStrategy": "TIERED",
                "priceRanges": [
                  {
                    "minUnits": 1,
                    "maxUnits": 10,
                    "price": 10
                  },
                  {
                    "minUnits": 10,
                    "price": 9
                  }
                ]
              },
              {
                "priceType": "MARKETPLACE_PRICE",
                "pricingStrategy": "TIERED",
                "priceRanges": [
                  {
                    "minUnits": 1,
                    "maxUnits": 10,
                    "price": 11.5
                  },
                  {
                    "minUnits": 10,
                    "price": 8.23
                  }
                ]
              }
            ]
          }
        ],
        "externalReferences": [
          {
            "ref": "1234",
            "type": "PURCHASE_ORDER"
          },
          {
            "ref": "90248ebe-64fa-11ed-9022-0242ac120002",
            "type": "SUBSCRIPTION"
          }
        ]
      }
    }
  }
}

C. Single Subscription, Recurring, USER and GIGABYTE units, Unit Ranges: 1-infinity, New Developer Price and Markup Price

Price Definition Mutation Request Example

mutation createPriceDefinition($input: CreatePriceDefinitionInput!) {
  createPriceDefinition(input: $input) {
    priceDefinition {
      id
      type
      pricingPlanId
      editionId
      productId
      items {
        pricingUnit
        costType
        costTypeCategory
        customMeteredUsage
        sources {
          priceType
          pricingStrategy
          priceRanges {
            minUnits
            maxUnits
            price
          }
        }
      }
      externalReferences {
        ref
        type
      }
    }
  }
}

Price Definition Mutation Variables Example

{
  "input": {
    "pricingPlanId": "05ca2a6c-64fa-11ed-9022-0242ac120002",
    "editionId": "7bcdae96-64fa-11ed-9022-0242ac120002",
    "productId": "818ead6c-64fa-11ed-9022-0242ac120002",
    "type": "BASE",
    "items": [
      {
        "costType": "RECURRING_PER_UNIT",
        "costTypeCategory": "RECURRING",
        "customMeteredUsage": false,
        "pricingUnit": "USER",
        "sources": [
          {
            "priceType": "BASE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": 10
              }
            ]
          },
          {
            "priceType": "MARKETPLACE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": 11.5
              }
            ]
          }
        ]
      },
      {
        "costType": "RECURRING_PER_UNIT",
        "costTypeCategory": "RECURRING",
        "customMeteredUsage": false,
        "pricingUnit": "GIGABYTE",
        "sources": [
          {
            "priceType": "BASE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": 10
              }
            ]
          },
          {
            "priceType": "MARKETPLACE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": 11.5
              }
            ]
          }
        ]
      }
    ],
    "externalReferences": [
      {
        "ref": "1234",
        "type": "PURCHASE_ORDER"
      },
      {
        "ref": "90248ebe-64fa-11ed-9022-0242ac120002",
        "type": "SUBSCRIPTION"
      }
    ]
  }
}

Price Definition Mutation Variables Template

{
  "input": {
    "pricingPlanId": "<pricing_plan_uuid>",
    "editionId": "<edition_uuid>",
    "productId": "<product_uuid>",
    "type": "BASE",
    "items": [
      {
        "costType": "RECURRING_PER_UNIT",
        "costTypeCategory": "RECURRING",
        "customMeteredUsage": false,
        "pricingUnit": "USER",
        "sources": [
          {
            "priceType": "BASE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": <new_developer_base_price for USER>
              }
            ]
          },
          {
            "priceType": "MARKETPLACE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "Price": <new_marketplace_price for USER>              }
            ]
          }
        ]
      },
      {
        "costType": "RECURRING_PER_UNIT",
        "costTypeCategory": "RECURRING",
        "customMeteredUsage": false,
        "pricingUnit": "GIGABYTE",
        "sources": [
          {
            "priceType": "BASE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": <new_developer_base_price for GIGABYTE>
              }
            ]
          },
          {
            "priceType": "MARKETPLACE_PRICE",
            "pricingStrategy": "UNIT",
            "priceRanges": [
              {
                "minUnits": 1,
                "price": <new_marketplace_price for GIGABYTE>
              }
            ]
          }
        ]
      }
    ],
    "externalReferences": [
      {
        "ref": "<purchase_order_id>",
        "type": "PURCHASE_ORDER"
      },
      {
        "ref": "<subscription_uuid>",
        "type": "SUBSCRIPTION"
      }
    ]
  }
}

Price Definition Mutation Response

{
  "data": {
    "createPriceDefinition": {
      "priceDefinition": {
        "id": "615c9d56551fa24714c8c3c6",
        "pricingPlanId": "05ca2a6c-64fa-11ed-9022-0242ac120002",
        "editionId": "7bcdae96-64fa-11ed-9022-0242ac120002",
        "productId": "818ead6c-64fa-11ed-9022-0242ac120002",
        "type": "BASE",
        "items": [
          {
            "costType": "RECURRING_PER_UNIT",
            "costTypeCategory": "RECURRING",
            "customMeteredUsage": false,
            "pricingUnit": "USER",
            "sources": [
              {
                "priceType": "BASE_PRICE",
                "pricingStrategy": "UNIT",
                "priceRanges": [
                  {
                    "minUnits": 1,
                    "price": 10
                  }
                ]
              },
              {
                "priceType": "MARKETPLACE_PRICE",
                "pricingStrategy": "UNIT",
                "priceRanges": [
                  {
                    "minUnits": 1,
                    "price": 11.5
                  }
                ]
              }
            ]
          },
          {
            "costType": "RECURRING_PER_UNIT",
            "costTypeCategory": "RECURRING",
            "customMeteredUsage": false,
            "pricingUnit": "GIGABYTE",
            "sources": [
              {
                "priceType": "BASE_PRICE",
                "pricingStrategy": "UNIT",
                "priceRanges": [
                  {
                    "minUnits": 1,
                    "price": 10
                  }
                ]
              },
              {
                "priceType": "MARKETPLACE_PRICE",
                "pricingStrategy": "UNIT",
                "priceRanges": [
                  {
                    "minUnits": 1,
                    "price": 11.5
                  }
                ]
              }
            ]
          }
        ],
        "externalReferences": [
          {
            "ref": "1234",
            "type": "PURCHASE_ORDER"
          },
          {
            "ref": "90248ebe-64fa-11ed-9022-0242ac120002",
            "type": "SUBSCRIPTION"
          }
        ]
      }
    }
  }
}

Step 2 - Price Change - GraphQL API

note

The Price Change API’s Authentication uses the Client Credentials grant type with ROLE_PARTNER and ROLE_PARTNER_READ scopes. This permits using API with marketplace API credentials, instead of a redirect to a Marketplace Manager role user.

The Authentication previously used the Authorization Code grant type with ROLE_CHANNEL_ADMIN scopes.

Authentication

Price Change is in the monolith
Price Change endpoints currently support authentication with fine-grained permissions, limited to ROLE_PARTNER (Read-Write) and ROLE_PARTNER_READ (Read)
- Credentials are OAuth2 Client Credentials
  - Create an API Client with Read-Write access
    - Client Type: Non-interactive application
    - Grant Types: Client Credentials
    - System-level scopes
      - Read and write = ROLE_PARTNER = if going to be creating or deleting price change requests
      - Read-only = ROLE_PARTNER_READ = if only need to retrieve price change requests
  - Configure your API tool or service for Authentication
    - Grant Type: Client Credentials
    - Consumer Key
    - Consumer Secret
    - Scope: ROLE_PARTNER or ROLE_PARTNER READ
    - Credentials: As Basic Auth Header
    - Start create token process
    - Get the Access Token and use with the API call

Single Subscription, Apply Price Definition to recurring units, on start of next billing period

On evergreen (non-contract) subscription, this will apply at the start of the next billing period.
On contract subscription, this will apply at the start of the next billing period. If the next billing period falls on the same date as the contract renewal date, it will get applied if the contract renews to the same plan. If the contract renews to a different plan, the prices from the other plan will be used and this price change will be ignored.
If the next billing period is also the date of discount end, the discount will end and the price change will be applied without the discount.
If there is an ongoing discount, the price change will be applied, and the discount will be recalculated according to the new prices after the price change.

Price Change Mutation Request Example

mutation ($subscriptionPriceChangeInput: SubscriptionPriceChangeInput!) {
  requestSubscriptionPriceChange(
    subscriptionPriceChangeInput: $subscriptionPriceChangeInput
  ) {
    subscription {
      id
    }
    priceDefinition {
      id
    }
    billingCharge {
      startDate
      totalPrice
      items {
        unit
        quantity
        salePrice
        totalPrice
      }
    }
    userErrors {
      __typeName
      ... on UserError {
        message
      }
    }
  }
}

Price Change Mutation Variables Example

{
  "subscriptionPriceChangeInput": {
    "subscriptionId": "0365fd14-f69d-4fe1-a83b-e6d451b8ac51",
    "priceDefinitionId": "615c9d56551fa24714c8c3c6",
    "strategy": "NEXT_BILLING_PERIOD"
  }
}

Price Change Mutation Variables Template

{
  "subscriptionPriceChangeInput": {
    "subscriptionId": "<uuid of subscription you want to apply price change>",
    "priceDefinitionId": "<price definition id in response from Step 1>",
    "strategy": "NEXT_BILLING_PERIOD"
  }
}

Response Mutation Response Example

{
  "data": {
    "requestSubscriptionPriceChange": {
      "subscription": {
        "id": "0365fd14-f69d-4fe1-a83b-e6d451b8ac51"
      }
      "priceDefinition": {
        "id": "615c9d56551fa24714c8c3c6"
      }
      "billingCharge": {
        "startDate": "2021-04-01",
        "totalPrice": "21.0000000000",
        "items": [
          {
            "unit": "USER",
            "quantity": "1.0000000000",
            "salePrice": "15.0000000000",
            "totalPrice": "15.0000000000"
          },
          {
            "unit": "GIGABYTE",
            "quantity": "4.0000000000",
            "salePrice": "1.5000000000",
            "totalPrice": "6.0000000000"
          }
        ]
      }
    }
  }
}

Single Subscription, with Contract, Apply Price Definition to recurring units, on start of next contract term

On contract subscription, this will apply at the end of the contract/start of next contract.
On contract subscription, this will apply at the start of the next billing period. If the next billing period falls on the same date as the contract renewal date, it will get applied if the contract renews to the same plan. If the contract renews to a different plan, the prices from the other plan will be used and this price change will be ignored.
If the next billing period is also the date of discount end, the discount will end and the price change will be applied without the discount.
If there is an ongoing discount, the price change will be applied, and the discount will be recalculated according to the new prices after the price change.

Price Change Mutation Request Example

mutation ($subscriptionPriceChangeInput: SubscriptionPriceChangeInput!) {
  requestSubscriptionPriceChange(
    subscriptionPriceChangeInput: $subscriptionPriceChangeInput
  ) {
    subscription {
      id
    }
    priceDefinition {
      id
    }
    billingCharge {
      startDate
      totalPrice
      items {
        unit
        quantity
        salePrice
        totalPrice
      }
    }
    userErrors {
      __typeName
      ... on UserError {
        message
      }
    }
  }
}

Price Change Mutation Variables Example

{
  "subscriptionPriceChangeInput": {
    "subscriptionId": "0365fd14-f69d-4fe1-a83b-e6d451b8ac51",
    "priceDefinitionId": "615c9d56551fa24714c8c3c6",
    "strategy": "NEXT_BILLING_PERIOD"
  }
}

Price Change Mutation Variables Template

{
  "subscriptionPriceChangeInput": {
    "subscriptionId": "<uuid of subscription you want to apply price change>",
    "priceDefinitionId": "<price definition id in response from Step 1>",
    "strategy": "NEXT_BILLING_PERIOD"
  }
}

Response Mutation Response Example

{
  "data": {
    "requestSubscriptionPriceChange": {
      "subscription": {
        "id": "0365fd14-f69d-4fe1-a83b-e6d451b8ac51"
      }
      "priceDefinition": {
        "id": "615c9d56551fa24714c8c3c6"
      }
      "billingCharge": {
        "startDate": "2021-04-01",
        "totalPrice": "21.0000000000",
        "items": [
          {
            "unit": "USER",
            "quantity": "1.0000000000",
            "salePrice": "15.0000000000",
            "totalPrice": "15.0000000000"
          },
          {
            "unit": "GIGABYTE",
            "quantity": "4.0000000000",
            "salePrice": "1.5000000000",
            "totalPrice": "6.0000000000"
          }
        ]
      }
    }
  }
}

Error Messages

Status	Code	Message	Reason
400	VALIDATION_ERROR	subscriptionId=%s contract auto-renews to a different pricing plan and can't be subject to a price change	Subscription is ending its current contract and auto-renewing to a different plan in the next billing period, so it is ineligible for price change. At the time of auto-renewal, the price on the new plan after renewal will be adopted.
400	VALIDATION_ERROR	Contract must exist and contract must auto-extend to the same pricingPlan %d	END_OF_CONTRACT strategy was used in Price Change Request and the subscription does not have a contract.
400	DISABLED_FEATURE	END_OF_CONTRACT price change feature is disabled for partner %s	END_OF_CONTRACT strategy was used in Price Change Request and this strategy is not enabled for marketplace.
400	VALIDATION_ERROR	No valid billing event date for order=%s
400	VALIDATION_ERROR	Cannot find company entitlement with subscriptionId=%s	Subscription not found with the Subscription UUID provided.
400	VALIDATION_ERROR	subscriptionId=%s is not active and can't be subject to a price change	Subscription is not in Active status.
400	VALIDATION_ERROR	subscriptionId=%s is imported and can't be subject to a price change	Subscription is for an imported product and thus has no associated pricing. In effect, it’s just a subscription with no billing, so changing price is invalid.
400	VALIDATION_ERROR	subscriptionId=%s has a pending event and can't be subject to a price change	Subscription already has a pending operation like an upcoming plan change or unit increase/decrease, that will conflict with the price change operation.
400	VALIDATION_ERROR	Discount with discountId = 5d0d26b5-3481-11e9-8e1f-02bf2c74dd2d, partner = VFZA, not applicable to productUUID = 1ab962b0-4257-44b8-bee1-71746e4bf25f, editionUUID = 97c67eb4-b536-4800-8c2c-f806df9bfa92, pricingPlanUUID = fe30d98e-f9b6-4960-b1e8-1c9f28740a0a	TBD

Additional Operations

Lookup Price Definition by ID - GraphQL API

Price Definition Query Request Example

query priceDefinition($id: ID!) {
  priceDefinition(id: $id) {
    externalReferences {
      ref
      type
    }
    id
    type
    items {
      pricingUnit
      costType
      costTypeCategory
      sources {
        priceType
        pricingStrategy
        priceRanges {
          minUnits
          maxUnits
          price
        }
      }
    }
  }
}

Price Definition Query Variables Example

{
  "id": "615c9d56551fa24714c8c3c6"
}

Price Definition Query Variables Template

{
  "id": "<id of price definition>"
}

Price Definition Query Response Example

{
   "id": "615c9d56551fa24714c8c3c6",
   "type":"BASE",
   "externalReferences": {
      "ref": "1234",
      "type": "PURCHASE_ORDER"
   }
   "items":[
      {
         "pricingUnit":"USER",
         "costType":"RECURRING_PER_UNIT",
         "costTypeCategory":"RECURRING",
         "sources":[
            {
               "priceType":"BASE_PRICE",
               "pricingStrategy":"UNIT",
               "priceRanges":[
                  {
                     "minUnits":1,
                     "maxUnits":null,
                     "price":10
                  }
               ]
            },
            {
               "priceType":"MARKETPLACE_PRICE",
               "pricingStrategy":"UNIT",
               "priceRanges":[
                  {
                     "minUnits":1,
                     "maxUnits":null,
                     "price":15
                  }
               ]
            }
         ]
      }
   ]
}

Find Price Definition by External Reference - GraphQL API

Price Definition Query Request Example

query priceDefinitionByExternalRef(
  $ref: String!
  $type: ExternalReferenceType!
) {
  priceDefinitionByExternalRef(ref: $ref, type: $type) {
    externalReferences {
      ref
      type
    }
    id
    type
    items {
      pricingUnit
      costType
      costTypeCategory
      sources {
        priceType
        pricingStrategy
        priceRanges {
          minUnits
          maxUnits
          price
        }
      }
    }
  }
}

Price Definition Query Variables Example

{
  "ref": "1234",
  "type": "PURCHASE_ORDER"
}

Price Definition Query Variables Template

{
  "ref": "<external reference value to search on",
  "type": "<external reference type to search on"
}

Price Definition Query Response Example

{
   "id": "615c9d56551fa24714c8c3c6",
   "type":"BASE",
   "externalReferences": {
      "ref": "1234",
      "type": "PURCHASE_ORDER"
   }
   "items":[
      {
         "pricingUnit":"USER",
         "costType":"RECURRING_PER_UNIT",
         "costTypeCategory":"RECURRING",
         "sources":[
            {
               "priceType":"BASE_PRICE",
               "pricingStrategy":"UNIT",
               "priceRanges":[
                  {
                     "minUnits":1,
                     "maxUnits":null,
                     "price":10
                  }
               ]
            },
            {
               "priceType":"MARKETPLACE_PRICE",
               "pricingStrategy":"UNIT",
               "priceRanges":[
                  {
                     "minUnits":1,
                     "maxUnits":null,
                     "price":15
                  }
               ]
            }
         ]
      }
   ]
}

Lookup Price Change events - GraphQL API

Price Change Query Request Example

query priceChangeBySubscriptionId($id: ID!) {
  priceChangeBySubscriptionId(id: $id) {
    subscription {
      id
    }
    priceDefinition {
      id
    }
    billingCharge {
      startDate
      totalPrice
      items {
        unit
        quantity
        salePrice
        totalPrice
      }
    }
  }
}

Price Change Query Variables Example

{
  "id": "0365fd14-f69d-4fe1-a83b-e6d451b8ac51"
}

Price Change Query Variables Template

{
  "id": "<id of subscription>"
}

Price Definition Query Response Example

{
    "subscription": {
      "id": "0365fd14-f69d-4fe1-a83b-e6d451b8ac51"
    }
    "priceDefinition": {
      "id": "615c9d56551fa24714c8c3c6"
    }
    "billingCharge": {
        "startDate": "2021-04-01",
        "totalPrice": "21.0000000000",
        "items": [
            {
                "unit": "USER",
                "salePrice": "15.0000000000",
                "quantity": "1.0000000000",
                "totalPrice": "15.0000000000"
            },
            {
                "unit": "GIGABYTE",
                "salePrice": "1.5000000000",
                "quantity": "4.0000000000",
                "totalPrice": "6.0000000000"
            }
        ]
    }
}

Was this page helpful?

Tell us more…

Help us improve our content. Responses are anonymous.

Thanks

We appreciate your feedback!

Using the GraphQL APIs

Step 1 - Create Price Definition - GraphQL API​

Authentication​

A. Single Subscription, Recurring, USER unit only, Unit Range: 1-infinity, New Developer Price and Markup Price​

Price Definition Mutation Request Example​

Price Definition Mutation Variables Example​

Price Definition Mutation Variables Template​

Price Definition Mutation Response​

B. Single Subscription, Recurring, USER unit only, Unit Ranges: Tiered 1-10 & 10-infinity, New Developer Price and Markup Price​

Price Definition Mutation Request Example​

Price Definition Mutation Variables Example​

Price Definition Mutation Variables Template​

Price Definition Mutation Response​

C. Single Subscription, Recurring, USER and GIGABYTE units, Unit Ranges: 1-infinity, New Developer Price and Markup Price​

Price Definition Mutation Request Example​

Price Definition Mutation Variables Example​

Price Definition Mutation Variables Template​

Price Definition Mutation Response​

Step 2 - Price Change - GraphQL API​

Authentication​

Single Subscription, Apply Price Definition to recurring units, on start of next billing period​

Price Change Mutation Request Example​

Price Change Mutation Variables Example​

Price Change Mutation Variables Template​

Response Mutation Response Example​

Single Subscription, with Contract, Apply Price Definition to recurring units, on start of next contract term​

Price Change Mutation Request Example​

Price Change Mutation Variables Example​

Price Change Mutation Variables Template​

Response Mutation Response Example​

Error Messages​

Additional Operations​

Lookup Price Definition by ID - GraphQL API​

Price Definition Query Request Example​

Price Definition Query Variables Example​

Price Definition Query Variables Template​

Price Definition Query Response Example​

Find Price Definition by External Reference - GraphQL API​

Price Definition Query Request Example​

Price Definition Query Variables Example​

Price Definition Query Variables Template​

Price Definition Query Response Example​

Lookup Price Change events - GraphQL API​

Price Change Query Request Example​

Price Change Query Variables Example​

Price Change Query Variables Template​

Price Definition Query Response Example​

Was this page helpful?

Tell us more…

Step 1 - Create Price Definition - GraphQL API

Authentication

A. Single Subscription, Recurring, USER unit only, Unit Range: 1-infinity, New Developer Price and Markup Price

Price Definition Mutation Request Example

Price Definition Mutation Variables Example

Price Definition Mutation Variables Template

Price Definition Mutation Response

B. Single Subscription, Recurring, USER unit only, Unit Ranges: Tiered 1-10 & 10-infinity, New Developer Price and Markup Price

Price Definition Mutation Request Example

Price Definition Mutation Variables Example

Price Definition Mutation Variables Template

Price Definition Mutation Response

C. Single Subscription, Recurring, USER and GIGABYTE units, Unit Ranges: 1-infinity, New Developer Price and Markup Price

Price Definition Mutation Request Example

Price Definition Mutation Variables Example

Price Definition Mutation Variables Template

Price Definition Mutation Response

Step 2 - Price Change - GraphQL API

Authentication

Single Subscription, Apply Price Definition to recurring units, on start of next billing period

Price Change Mutation Request Example

Price Change Mutation Variables Example

Price Change Mutation Variables Template

Response Mutation Response Example

Single Subscription, with Contract, Apply Price Definition to recurring units, on start of next contract term

Price Change Mutation Request Example

Price Change Mutation Variables Example

Price Change Mutation Variables Template

Response Mutation Response Example

Error Messages

Additional Operations

Lookup Price Definition by ID - GraphQL API

Price Definition Query Request Example

Price Definition Query Variables Example

Price Definition Query Variables Template

Price Definition Query Response Example

Find Price Definition by External Reference - GraphQL API

Price Definition Query Request Example

Price Definition Query Variables Example

Price Definition Query Variables Template

Price Definition Query Response Example

Lookup Price Change events - GraphQL API

Price Change Query Request Example

Price Change Query Variables Example

Price Change Query Variables Template

Price Definition Query Response Example