Connect Gorgias and manage subscriptions from tickets

By the end of this tutorial, every Gorgias ticket shows a card with the customer’s Curobi subscriptions, and your agents can skip, pause, resume, reschedule or cancel one without leaving the ticket. It takes about thirty minutes the first time. You’ll copy and paste a few URLs; there’s no code.

Before you start

• You’re on Curobi’s Pro plan, on a paid Shopify plan.
• You have admin access to your Gorgias account. The HTTP integration this uses is on every Gorgias Helpdesk plan.
• You know a customer with a Curobi subscription, to test with. Only subscriptions created through Curobi appear on the card; one another subscription app created won’t.

Everything happens in Gorgias except step 1, which is in Curobi under Data & API → API keys.

1. Create an API key in Curobi

1. In Curobi, open Data & API → API keys and click Create API key.
2. Key type: Server key (the one that starts curobi_sk_). A Browser key can’t change subscriptions or look customers up, so it won’t work here.
3. Key name: Gorgias.
4. Tick exactly these three permissions:
   • under Subscriptions: read:subscriptions, so Gorgias can read the subscriptions for the card
   • under Changing subscriptions: write:subscriptions, so the buttons can change them
   • under Customer data: read:customers (“Include customer names and email addresses in responses”). Gorgias needs this to look subscriptions up by email. The card itself shows no names or emails.
5. Click Create API key. The API key created dialog shows the key once: copy it now. It starts with curobi_sk_live_. Keep it somewhere safe for steps 2 and 5.

If the key is ever exposed, revoke it on the same page and create a new one. Gorgias keeps working once you paste the new key into the integration and into each button.

2. Add the HTTP integration in Gorgias

1. In Gorgias, open Settings → App Store → HTTP Integration, then on the Manage tab click Add HTTP Integration.

2. Integration name: CUROBI Subscriptions.

3. Triggers: tick Ticket created and Ticket updated. Leave the rest unticked.

4. URL (one line, exactly):

   https://app.curobi.com/api/admin/v1/subscriptions?email={{ticket.customer.email}}&limit=10

   {{ticket.customer.email}} is a Gorgias variable. Gorgias fills in the ticket’s email address when it calls Curobi. You’ll see it as email=name%40example.com in the Events tab; that’s normal.

5. HTTP method: GET. Response content type: application/json.

6. Under Headers, add one header. The form has a Key field and a Value field, and it’s easy to put them the wrong way round:

   • Key: Authorization
   • Value: Bearer followed by a space and your key, for example Bearer curobi_sk_live_7f3aQ2…

7. Click Add integration.

3. Check that it’s receiving data

1. Create a ticket for a customer who has a subscription. The quickest way is New ticket in the Gorgias inbox, with that customer’s email address in the To field and any message. Or have them email your support address.
2. Go back to Settings → App Store → HTTP Integration, open CUROBI Subscriptions and its Events tab. You should see one or two GET rows to app.curobi.com with 200 OK. Two rows for one ticket is normal: Gorgias calls once for Ticket created and once more for its own update of the ticket.
3. Click a row. The Request side should list a header Authorization: REDACTED. The Response side is the customer’s subscriptions, starting "data": [.
4. If it isn’t 200 OK:
   • 401, and the Request side lists a header called Bearer instead of Authorization: the Key and Value fields in step 2 are swapped.
   • 403 with plan_upgrade_required: the store isn’t on Pro, or is a development store.
   • 403 with insufficient_scope: go back to step 1 and check all three permissions are ticked.
5. If there are no rows at all, open the ticket and add any tag to it. That’s a Ticket updated event, and it makes Gorgias call Curobi.

4. Put the card in the sidebar

1. Open the ticket from step 3. On the thin icon bar at the far right of the screen, click the cog (below the star).

2. In the menu, choose Edit widget data → Add new widget. The ticket area changes to Manage widgets, and the sidebar to Editing Custom widgets.

3. Under HTTP data you’ll see CUROBI Subscriptions. Drag it into the sidebar on the right. The whole response lands there: a Next cursor field at the top, then a Data section listing every field of a subscription.

4. Hover over a field to get its trash and pencil icons. Trash Next cursor. In the Data section, trash everything except these eight, and rename the ones you keep with the pencil:

   Field	Rename to
   status	Status
   product_title	Products
   frequency_label	Bills
   next_billing_at	Next charge
   charge_amount	Amount
   currency_code	Currency
   order_name	Started with order
   number	Subscription #

   Keep number visible: it’s the id the buttons use, and it helps when you contact Curobi support about a specific subscription.

5. Click the pencil next to the Data heading and rename it Subscriptions.

6. Click Save, then close Manage widgets with the ×.

On the ticket, the card now shows one collapsed block per subscription, each titled with the name you gave the section. Click a block’s chevron to open it and see the fields. Cancelled subscriptions are listed too, so an agent can see what a customer used to have.

5. Add the five buttons

Open the editor again (cog → Edit widget data → the CUROBI widget). In the sidebar, under the Subscriptions (Data) section, click Add Button.

The Configure HTTP action dialog has these parts. Fill them in the same way for every button:

• Method: POST
• Headers: one row. Label Authorization, Key Authorization, Value Bearer followed by a space and your key (the same as step 2). Leave Editable and Required unticked. Every button needs its own copy of this header: a button without it fails with 401, because the integration’s header doesn’t apply to buttons.
• Query Parameters: leave empty. The safety key is already in the URL.
• Body: choose application/json and type the body given for that button below.

Then give each button its title, URL and body. Copy each URL exactly, on one line.

Skip next order · body {}

https://app.curobi.com/api/admin/v1/subscriptions/{{data[$listIndex].number}}/skip?idempotency_key=gorgias-{{ticket.id}}-{{data[$listIndex].number}}-skip-{{data[$listIndex].next_billing_at}}

Pause · body {}

https://app.curobi.com/api/admin/v1/subscriptions/{{data[$listIndex].number}}/pause?idempotency_key=gorgias-{{ticket.id}}-{{data[$listIndex].number}}-pause-{{data[$listIndex].updated_at}}

Resume · body {}

https://app.curobi.com/api/admin/v1/subscriptions/{{data[$listIndex].number}}/resume?idempotency_key=gorgias-{{ticket.id}}-{{data[$listIndex].number}}-resume-{{data[$listIndex].updated_at}}

Reschedule · body { "next_billing_at": "" }. Tick Editable on next_billing_at so the agent can type a date, and Required so it must be filled in.

https://app.curobi.com/api/admin/v1/subscriptions/{{data[$listIndex].number}}/reschedule?idempotency_key=gorgias-{{ticket.id}}-{{data[$listIndex].number}}-reschedule-{{data[$listIndex].updated_at}}

Cancel · body {}

https://app.curobi.com/api/admin/v1/subscriptions/{{data[$listIndex].number}}/cancel?idempotency_key=gorgias-{{ticket.id}}-{{data[$listIndex].number}}-cancel

The parts in double curly brackets are filled in by Gorgias with the subscription the agent clicked and the ticket they’re on. The long idempotency_key is a safety catch: if an agent double-clicks, or Gorgias sends a request again, Curobi runs the change once. Why each key ends the way it does is explained in Why a double-click doesn’t skip twice.

Click Save in the dialog after each button, then Save on the widget. The buttons appear at the top of every subscription block on the card.

6. Test one button before you hand it to the team

1. Open a block whose Status is ACTIVE and click Pause.
2. A green confirmation means it worked. A few seconds later the block’s Status reads PAUSED, and in Curobi → Subscriptions the subscription shows as paused.
3. Click Resume on the same block to put it back.

If you get a red Something went wrong on your last action toast instead, it opens a Request panel. If its Headers list only Content-Type, the button is missing its Authorization header: edit it as in step 5. For any other error, see Troubleshooting.

Next steps

• Brief your team on what each button does, especially that Cancel is final and that Reschedule wants a future date. See What each button does.
• Know where to look when the card is empty. It’s usually a customer writing in from a different address than the one on their Shopify account. See What agents see.
• Know how to switch it off. Revoking the Gorgias key in Curobi stops the card and every button at once. See Disconnecting.