Update Usage-Based Charges

This endpoint allows app partners to bill a merchant for their usage of an app on a usage-based plan. Use it to post the amount the merchant owes now, so billing follows their pay-as-you-go consumption.

🔑Scopes

Subscription.read_write - Subscription Read & Write

Two charges per merchant, per calendar month

The window is the calendar month — not 30 days, and not a billing cycle. A usage-based subscription has no billing cycle: it never renews and has no end date. The limit resets on the 1st of each month, with no reference to the merchant's subscription date.

The count includes any charge still unpaid, however old, plus any charge paid during the current month.

An unpaid charge is replaced, not added to

If the merchant has an unpaid charge, a further call does not create a second charge. It replaces that charge's amount and description — and you may do that once per calendar month.

So the calls available to you depend on whether the merchant is settling:

Situation	Calls available
The merchant settles each charge	2 per calendar month
A charge was created this month and is still unpaid	2 — one to create, one to replace
An unpaid charge carried over, and it stays unpaid all month	1 — the merchant settling it reopens the second call

The cap is never more than two, but the second call is only available if the merchant settles in between. If a balance sits unpaid for the whole month you get one call that month — so you cannot add mid-month usage onto a balance the merchant has not yet paid. Design your billing around that.

A paid charge is never reopened

If the previous charge was already paid, this call creates a new, separate charge for the full amount you send, and the settled charge is left untouched — it is never adjusted, credited, or offset against the new one.

Send the amount you want collected now, not a running total. Against an unpaid charge you are restating the outstanding balance; against a settled one you are adding a new bill.

Charges are billed after usage, never prepaid — you cannot sell a merchant a pack of credits up front. The merchant settles each charge from their Zid dashboard, so allow time for them to act.

The plan's starting price is charged once, when the merchant subscribes, and never again. If you want a fixed monthly amount as well as metered usage, include it in the charge you post each month. See Usage-based plans.

Responses

🟢200OK

application/json

The charge was created, or an existing unpaid charge was replaced. The response does not distinguish the two — compare the returned charge.id with the one you saw previously, or call Subscription Details, to tell which happened.

Bodyapplication/json

🟠401Unauthorized

🟠422Unprocessable Entity

🔴500Internal Server error

curl --location 'https://api.zid.sa//v1/managers/market/apps/plans/subscription-charge' \ --header 'Accept: application/json' \ --header 'Accept-Language: en' \ --header 'X-Manager-Token: eyJpdiI6IlA3WTFZbWk1YVBTQnNrYkRtOFBGZGc9PSIsInZhbHVlIjoiL3QvVmtuMHFQdGNMdkNwZ0FCZkh3Y1l4aEs5NDhGVnFXbWVZYlFJb2kucdcNrekppN09CVTlnYlducjRLbjhXNzhFTFhhZDZTSXdRbUphSEYyUkZJWTJFZ0h3Ymlzb1RVNmxlaEkjgftrmpIZ1RmZXVFYUszZG5DZDZjbTRqNzByNVBMTktzYkQ3WGQ5MDhqbWo2NWFkT3MvRExmYVY4YXBCakkwSjR1L2pTbUR4dWZvd2h5K2tTQlAvRlN2TnZuOVFROW42WTRqZmtkWUZWem4rRXFLVU00aGJtQT0iLCJtYWMiOiJjM2U2ZGRmMjY1ZjFmMmI5YjZlMzFkMGFhNmMzYjM5ZjhiOWE0YjVhMzU2ZTRhYTkxOTVlYmFiMTVkY2I1NWQ2IiwidGFnIjoiIn0=' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxMTciLCJqdGkiOiJhMTg5ZTg3MmYxMzhkMWVhYjU5MjVkMDkyMGE5NmI0YjliNjg0Y2E2ZTdmM2M2MjljZWYxNmQ4NDJjMmJlYmVhMjI4YTdmMTA0ZWQ4NWE5NCIsImlhdCI6MTY3OTU3Njk5OS41NjY4NzcsIm5iZiI6MTY3OTU3Njk5OS41NjY4OCwiZXhwIjoxNzExMTk5Mzk5LjQ4NjE1Mywic3ViIjoiMTgyNDc1Iiwic2NvcGVzIjpbInRoaXJkLXBhcnRpZXMtYXBpcyJdfQ.i07ef09nVNXGZF-g-QXpNoS2vlFQK_zntAqAMS4Az2XD2EyMLhxLZZRL-QlR11zUPqMmXjMAl_4ooKa3M3zkfZQ6Ga6qStvamk8RnC_39VUx0lfN2A4k65ERZpqwrMy6-t3dE99zay3aicIdNvbgi0zeuMSE5Tn99u-2AtSRa8ffbfAcYPPXacHrhdmlYzdiZS_x_skovFEow1E-nDjdL1WHqO92XdZ7RfNLkiYFTjZlZmM_UruvioaR3q6TXJbqRK_ZrziivezL8ohIQ2SBosUp58I29rlKzvlw_R2j0rKKYZbdxYDaxAHOISmOFKAlO66k7dNevAHI3s4uGIjoGA6ZXHknccWPLLLiaAQ0r64HV8GowW5dg2rhZNurJGDTnLlBQ6F-ql42ptHzSAfzzi576CEoN3gMVpgXcbntUY3reETkFsTBPUjeSuMpANMioXAA0GRp3Ut-84fTnrWxqsCW1WVUIx33HvmfCGPXIdkaCCWoA6G6KXo04MtFbKXQmXkK9esQWI-rqdVnMD3zSR3g3yFHZSL1U-mZeNja03706Rav1ordsRNOtRwtLuoRRbk9KasbUpEwqq4Ao9lqZZwRIjdEw-pQtnUT8V53fhmuuRIefCLFO7eGEtGUnh9o6Uh_pgi6AB6uSlnN9GEMGgI1alqvMmTjxvC-HHt0V-Y' \ --header 'Content-Type: application/json' \ --data '{ "amount": 49.5, "description": { "ar": "استخدام 500 رسالة - أكتوبر", "en": "500 messages used - October" } }'

{ "status": "object", "charge": { "id": "9eaac8b0-3530-4bdb-b2fb-34b4efe22179" }, "message": { "type": "object", "code": null, "name": null, "description": "Subscription charge was updated successfully" } }

Update Usage-Based Charges

Request

Responses