Buy Now Item

buyNowItem is very similar to addItem. The main difference is it will always create a new order for the item added and the SDK will automatically redirect your website to checkout (skipping cart). It also has some additional properties documented below.

Usage

buyNowItem takes in the following object.

interface BuyNowItemRequest {
    lineItem: AddLineItem | BuyNowSubscriptionLineItem;
    fulfillment: CartFulfillment;
    locationId: string;
}

• lineItem represents the item you want to buy now. It can be an AddLineItem (covered in addItem) or a BuyNowSubscriptionLineItem.
  • BuyNowSubscriptionLineItem is used if you want to buy an item as a subscription (it must be configured with a subscription offering on the Square Online dashboard). It’s basically AddLineItem with reduced modifier types and a subscriptionPlanVariationId. Buying an item as a subscription will re-direct to /s/subscription-checkout which is the checkout route used for subscriptions. It will also set a com_subscription_cart_token cookie that is used by the subscription checkout.

    interface BuyNowSubscriptionLineItem extends AddLineItem {
        modifiers?: BuyNowSubscriptionItemModifier[];
        subscriptionPlanVariationId: string;
    }
    

    • modifiers for a buy now subscription line item are the same format as covered in the SDK’s item helpers’ modifier validation. The only difference, is that you are limited to only the CHOICE or TEXT modifier types.

        type BuyNowSubscriptionItemModifier = ChoiceModifier | TextModifier;
      

    • subscriptionPlanVariationId is the variation ID for a subscription plan. It can be found on an item’s subscriptions property. For example, to get the first variation ID for the first subscription plan you would access it via item.subscriptions.0.subscription_plan_data.subscription_plan_variations.0.id.
• fulfillment and locationdId are the exact same as covered in addItem. The only exception is fulfillment.fulfillmentType must be SHIPMENT if you are using a BuyNowSubscriptionLineItem for the lineItem.

Example

// With the limited modifier types available for a BuyNowSubscriptionLineItem
const buyNowItemRequest = {
    lineItem: {
        itemId: '47HCEE6ZQUFFY3Y7X52CRVCO',
        variationId: '6YOTMYGOFTJR4PTTYRCLE7BH',
        modifiers: [
            {
                id: '6WVGAE3PKEHRWZHF54KR2PIN',
                type: 'CHOICE',
                choiceSelections: ['E3MWZ3PJ3VZDQWGW4G3KFZGW', 'GKCUYTB7ARN25J7BTRTOSVHO']
            },
            {
                id: '11ede91fbff63a3ab4dbde667deefb9b',
                type: 'TEXT',
                textEntry: 'my t-shirt-text'
            }
        ],
        quantity: 4,
        subscriptionPlanVariationId: 'BUZAK2FAA5RZ2T3GVBOP36M2'
    },
    fulfillment: {
        fulfillmentType: 'SHIPMENT', // must be SHIPMENT for subscriptions
        setPastTimeToCurrent: true,
    },
    locationId: 'L36RW9ABXQTEE'
};

New Order and Cart Order Cookies

As mentioned, buyNowItem will always create a new order. For an AddLineItem used in lineItem, it will create a brand new regular order (as if using addItem with no existing order). This means if the buyNowItem successfully adds the item, new com_cart_id and com_cart_token cookies are added (replacing any existing values). You’ll need to capture these cookies yourself if you want to make use of them for multiple cart management (assuming your buyer returns to your Custom Sites pages from the checkout redirect).

For a BuyNowSubscriptionLineItem used in lineItem, it will create a brand new subscription order which is different than the order used for an AddLineItem. If the buyNowItem successfully adds the item, a new com_subscription_cart_token cookie is added (again, replacing any existing value). This is the token used to load the order in subscription checkout (/s/subscription-checkout). Note that with subscriptions there can only ever be a single variation of an item (not quantity of an item) in a subscription order.

Redirect and Error Handling

On successful addition of an item by buyNowItem, it will either redirect your website to /s/checkout for an AddLineItem or /s/subscription-checkout for a BuyNowSubscriptionLineItem. That is, the SDK will set window.location.href = response.url for the appropriate redirect.

For errors, it will throw the same as addItem. Reference that documentation on how to handle errors.

try {
    await sdk.cart.buyNowItem(buyNowItemRequest);
} catch (error) {
    // Display 'Something went wrong' to the buyer
}