Can I create a payment link for a subscription with an existing customer Id?

Questions
1

I’m trying to figure out how to use the payment link API to create a payment link for a subscription. In the Square documentation / tutorial (Subscription Plan Checkout) it shows how to create a quick pay checkout for a subscription. However, this does not allow me to submit a customer id.

Is it possible to do an Order Checkout for a subscription. If so, how? When I tried it with the API, I got this error:

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "INVALID_VALUE",
      "detail": "Invalid object `{{subscription_id}}`: incorrect object type `SUBSCRIPTION_PLAN`.",
      "field": "subscription_plan_id"
    }
  ]
}

If not, what is the way to connect a subscription with a customer in my system?

2

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Checkout API
Square Developer
Checkout API

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

To connect a subscription with a customer in your system, you need to create a checkout link for a Square subscription plan using the Checkout API’s CreatePaymentLink endpoint. This will generate a Square-hosted checkout page for buyers to pay and subscribe to the plan.

However, the Checkout API does not currently support the ability to specify a customer ID when creating a checkout link for a subscription plan. The customer is created or identified based on the phone number provided during the checkout process. If a customer with the provided phone number doesn’t exist in the seller’s Customer Directory, the API creates a new customer. If a customer with the provided phone number does exist, the API uses that existing customer.

After the buyer pays for the subscription, Square automatically creates a customer profile (if one doesn’t already exist) and adds a card on file to the customer profile. The card on file is then charged for the first priced subscription phase and for recurring payments as defined by the subscription plan.

If you need to connect the subscription with a specific customer in your system, you could potentially use the phone number as a unique identifier to match the Square customer with your system’s customer record.

This answer was reviewed by @Bryan-Square.

5

Can the customer opt to not provide a phone number during checkout? And what happens in that case?

6

Yes, they can checkout as a guest. The checkout will then create new customer profile with the collected information. :slightly_smiling_face:

7

Gotcha. Thanks for answering. If you don’t mind, I have a few followups.

According to the payment link documentation, once the customer completes checkout, an order object will be generated. What does that order object look like for a subscription? Will it have the subscription plan id as a line item? Does it stay open for the duration of the subscription? Is there a way to test workflow through developer dashboard?

Thanks!

8

A subscription order will look like this:

{
    "order": {
        "id": "xP2CcqcQx1h8VHkKOm2yQtBelGYZY",
        "location_id": "3Z4V4WHQK64X9",
        "line_items": [
            {
                "uid": "8e73sZ5LAPJbWt5HLwsdwC",
                "quantity": "1",
                "name": "Coffee membership fees",
                "base_price_money": {
                    "amount": 100,
                    "currency": "USD"
                },
                "gross_sales_money": {
                    "amount": 100,
                    "currency": "USD"
                },
                "total_tax_money": {
                    "amount": 0,
                    "currency": "USD"
                },
                "total_discount_money": {
                    "amount": 0,
                    "currency": "USD"
                },
                "total_money": {
                    "amount": 100,
                    "currency": "USD"
                },
                "variation_total_price_money": {
                    "amount": 100,
                    "currency": "USD"
                },
                "item_type": "ITEM",
                "total_service_charge_money": {
                    "amount": 0,
                    "currency": "USD"
                }
            }
        ],
        "fulfillments": [
            {
                "uid": "QRZZlLL7DYJ8NHXlzpyBKC",
                "type": "DIGITAL",
                "state": "PROPOSED"
            }
        ],
        "created_at": "2024-09-30T21:03:04.846Z",
        "updated_at": "2024-09-30T21:06:52.784Z",
        "state": "DRAFT",
        "version": 7,
        "total_tax_money": {
            "amount": 0,
            "currency": "USD"
        },
        "total_discount_money": {
            "amount": 0,
            "currency": "USD"
        },
        "total_tip_money": {
            "amount": 0,
            "currency": "USD"
        },
        "total_money": {
            "amount": 100,
            "currency": "USD"
        },
        "total_service_charge_money": {
            "amount": 0,
            "currency": "USD"
        },
        "net_amounts": {
            "total_money": {
                "amount": 100,
                "currency": "USD"
            },
            "tax_money": {
                "amount": 0,
                "currency": "USD"
            },
            "discount_money": {
                "amount": 0,
                "currency": "USD"
            },
            "tip_money": {
                "amount": 0,
                "currency": "USD"
            },
            "service_charge_money": {
                "amount": 0,
                "currency": "USD"
            }
        },
        "source": {
            "name": "Boats"
        },
        "customer_id": "JNABMXH5HN7597FTNH3FD4GX78",
        "net_amount_due_money": {
            "amount": 100,
            "currency": "USD"
        }
    }
}

You can then use SearchSubscriptions with the customer_id to get the subscription:

{
    "include": [
      "actions"
    ],
    "query": {
      "filter": {
        "customer_ids": [
          "JNABMXH5HN7597FTNH3FD4GX78"
        ],
        "location_ids": [
          "{{location_id}}"
        ]
      }
    }
  }

The subscription will look like:

{
    "subscriptions": [
        {
            "id": "30481d56-e677-4800-b5f9-8ad42ec5fc78",
            "location_id": "3Z4V4WHQK64X9",
            "customer_id": "JNABMXH5HN7597FTNH3FD4GX78",
            "start_date": "2023-10-26",
            "charged_through_date": "2024-10-26",
            "status": "ACTIVE",
            "invoice_ids": [
                "inv:0-ChCQFDnz32BIPwrahm5o8CrAEOcN"
            ],
            "buyer_self_management_token": "EJ3CVMhlEt8YxZipt5L0UvM0auxAd7zJnnb32CuDnIGV8QCpgEGQshte6YtBfE6nQ2HJCpQr_J1LN1CVfk7AIbpw2tCpEruWCARemaSOmGMppJgFp4sKvtMVwZTbzWMD2g==",
            "version": 1,
            "created_at": "2023-10-26T15:11:34-07:00",
            "card_id": "ccof:CA4SEGRgRl2e6_7BGrMxJPBtwCUoAg",
            "timezone": "America/Los_Angeles",
            "order_template_id": "JLGmll91l3iVIzdV7UsYVS1HgpKZY",
            "source": {
                "name": "Boats"
            },
            "phases": [
                {
                    "uid": "e4e82e90-ea41-46bf-9c6f-0be0c08ad892",
                    "ordinal": 0,
                    "order_template_id": "JLGmll91l3iVIzdV7UsYVS1HgpKZY",
                    "plan_phase_uid": "BKGDUY7OYMSLSUPAZCM7KCP4"
                }
            ],
            "plan_variation_id": "GZZAVQXQI3I5PFFTPDI4VQVM"
        },
        {
            "id": "130a903c-274a-4c45-90e0-660ab7f322f5",
            "location_id": "3Z4V4WHQK64X9",
            "customer_id": "JNABMXH5HN7597FTNH3FD4GX78",
            "start_date": "2024-09-30",
            "charged_through_date": "2024-10-30",
            "status": "ACTIVE",
            "invoice_ids": [
                "inv:0-ChA3DgmOi6gcaRb3tL1RJza7EOcN"
            ],
            "buyer_self_management_token": "EJ3CVMhlEt8YxZipt5L0UvODitFgKBvlWSA_-bMijh8qVEe5sLmBYWE0-jtYjnMOKk3ZxxhuoVY1J6xrp1QaNPoLLEk71N3W4IQCmdu3LgDwv5S19pL5IcyUOoOv78Dvmw==",
            "version": 1,
            "created_at": "2024-09-30T14:06:52-07:00",
            "card_id": "ccof:CA4SEDs8SJescv4M3WjY-UyqAWAoAg",
            "timezone": "America/Los_Angeles",
            "order_template_id": "xP2CcqcQx1h8VHkKOm2yQtBelGYZY",
            "source": {
                "name": "Boats"
            },
            "monthly_billing_anchor_date": 30,
            "phases": [
                {
                    "uid": "c2db76a2-a9d1-4708-9815-e6772f977aa9",
                    "ordinal": 0,
                    "order_template_id": "xP2CcqcQx1h8VHkKOm2yQtBelGYZY",
                    "plan_phase_uid": "BAA4WZ63TVC3OMWMT3J6NR6I"
                }
            ],
            "plan_variation_id": "WJZ33ATP5ER36Y6Y2ZIE33SZ"
        }
    ]
}

:slightly_smiling_face:

9

Ah okay.

That addresses my issue. Thanks.