Skip to main content

Build a Pre-order and Try Before You Buy (TBYB) solution

You can create pre-order and TBYB options using the GraphQL Admin API's sellingPlanGroupCreate mutation. This guide describes the requirements for creating pre-order or TBYB options and shows you how to manage them using the GraphQL Admin API.

Anchor to RequirementsRequirements

  • Your app can make authenticated requests to the GraphQL Admin API.

  • Your app has the following access scopes:

  • You've familiarized yourself with selling plans and pre-orders and TBYB.

  • You've created products and product variants in your development store.

  • The merchant that you're developing for meets the qualifying criteria.

    Note
    • Most subscriptions, pre-order and try before you buy apps need to request API access through the Partner Dashboard. We give API access to apps that are designed according to our [principles for subscriptions, pre-order and TBYB apps] (/docs/apps/selling-strategies/purchase-options#shopifys-principles).
    • Public apps that use subscriptions, pre-order or TBYB need to meet specific requirements to be published on the Shopify App Store.
    • Custom apps created in the Shopify admin can't use subscriptions, pre-order or TBYB because these apps can't use extensions or request access to protected scopes. If you're building a solution for a single store, then build your custom app in the Partner Dashboard.

Anchor to Step 1: Create pre-order and TBYB optionsStep 1: Create pre-order and TBYB options

Caution

Subscriptions, pre-orders, TBYB, and associated records, including SellingPlanGroup, SellingPlan, policies, and associations to products and variants, are deleted 48 hours after a user uninstalls a subscriptions, pre-orders, or TBYB app. Products and product variants aren't deleted. We recommend backing up Subscriptions, pre-orders, and TBYB records in case you need to restore them later.

Create pre-order and TBYB options using the sellingPlanGroupCreate mutation. The SellingPlanGroup object includes one or more SellingPlan objects. The SellingPlan object specifies how a product can be sold.

Learn more about GraphQL Admin API objects for selling plans. For more information on input fields and values, refer to the following resources:

Note

SellingPlan objects are grouped together in Liquid when they are created by the same app, and when they have the same selling_plan_group.name and selling_plan_group.options values. For more information, refer to the selling_plan_group object.

Create a pre-order with a selling plan (SellingPlan) that contains the following policies:

  • Billing (billingPolicy.fixed): The 20% of the total amount will be charged as a deposit at checkout. The remaining amount will be charged on 2022-07-24.

  • Delivery (deliveryPolicy.fixed): The fulfillment timeline is unknown.

  • Pricing (pricingPolicies.fixed): A 15% product reduction is applied to the variant.

  • Inventory (inventoryPolicy.reserve): The inventory will be updated when the order is fulfilled.

    The category field should be set to PRE_ORDER.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
sellingPlanGroupCreate(
input: {
name: "Pre-order"
merchantCode: "pre-order"
options: [
"Pre-order"
]
sellingPlansToCreate: [
{
name: "July 2022 release"
category: PRE_ORDER
options: [
"20% deposit. Balance due on July 24th 2022"
]
billingPolicy: {
fixed: {
checkoutCharge: {type: PERCENTAGE, value: {percentage: 20.0}}
remainingBalanceChargeTrigger: EXACT_TIME
remainingBalanceChargeExactTime: "2022-07-24"
}
}
pricingPolicies: [
{
fixed: {
adjustmentType: PERCENTAGE
adjustmentValue: { percentage: 15.0 }
}
}
]
deliveryPolicy: {fixed: {fulfillmentTrigger: UNKNOWN}}
inventoryPolicy: {reserve: ON_FULFILLMENT}
}
]
}
resources: {productVariantIds: [], productIds: []}
) {
sellingPlanGroup {
id
sellingPlans(first: 1) {
edges {
node {
id
}
}
}
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"sellingPlanGroupCreate": {
"sellingPlanGroup": {
"id": "gid://shopify/SellingPlanGroup/71434296",
"sellingPlans": {
"edges": [
{
"node": {
"id": "gid://shopify/SellingPlan/422674488",
}
}
]
}
},
"userErrors": []
}
},
"extensions": {
"cost": {
"requestedQueryCost": 62,
"actualQueryCost": 17
}
}
}

Anchor to Step 2 (Optional): Manage pre-order and TBYB optionsStep 2 (Optional): Manage pre-order and TBYB options

Anchor to Associate a pre-order or TBYB option to a product or product variantAssociate a pre-order or TBYB option to a product or product variant

You can use the sellingPlanGroupAddProducts mutation or the sellingPlanGroupAddProductVariants mutation to make a separate request to associate a pre-order or TBYB option with a product or product variant, without having to delete and recreate the pre-order or TBYB option.

Anchor to Associate multiple pre-order or TBYB options to a product or product variantAssociate multiple pre-order or TBYB options to a product or product variant

You can use the productJoinSellingPlanGroups mutation or the productVariantJoinSellingPlanGroups mutation to associate multiple pre-orders or TBYB to a product or product variant.

Anchor to Edit pre-order and TBYB optionsEdit pre-order and TBYB options

You can use the sellingPlanGroupUpdate mutation to edit the attributes associated with a pre-order or TBYB option. For example, you can change the pre-order or TBYB options name.

Anchor to Next stepsNext steps

Was this page helpful?