Billing & Account

Partner Hosting API for Website Builders

Let users of your website builder buy GHP Cloud hosting and publish their finished site to it, from order to live release.

9 min read

Partner Hosting API

The Partner Hosting API is for website builders that let their users publish a finished website straight to GHP Cloud. Your user designs the site in your product; when it is ready, you offer GHP Cloud hosting. The user pays GHP Cloud directly, gets a server of their own and their own GHP Cloud login, and you publish their website to it automatically.

Partner accounts are set up by GHP Cloud. See Becoming a partner at the end of this page.

How it works

  • 1. Recommend a size. Ask GHP Cloud which server size suits the website (POST /plans/recommend) and show the answer to your user.
  • 2. Create an order. POST /orders returns a checkoutUrl. Send your user there.
  • 3. Your user pays GHP Cloud. On GHP Cloud's own checkout page. If their email already has a GHP Cloud login, they sign in and approve adding the website to the plan they already pay for instead.
  • 4. GHP Cloud sets up the server. Usually within 20 minutes. You receive order.paid, then site.ready with the site id and a temporary address.
  • 5. You publish. Upload the finished build, then create a deployment. Follow the live log or wait for deployment.succeeded.

Every deployment is a new release. The website switches to it only after it is built and scanned for malware; if the new release does not answer, the previous one stays live. Nothing is built and no server is set up until your user has paid, and you only ever reach the websites your orders created. Your user can remove your access at any time from their GHP Cloud panel.

Basics

Base URL      https://api.ghpcloud.com/api/v1/partner
Auth          Authorization: Bearer ghpp_live_<key>     (sandbox: ghpp_test_<key>)
Format        JSON. Responses carry GHP-API-Version: 2026-11-01
Rate limit    Per partner (default 600 requests a minute); 429 with Retry-After
Pagination    ?limit=25&cursor=<id>  ->  { items, nextCursor }

Idempotency. Send an Idempotency-Key header (your own unique id) on POST /orders, POST /sites/{id}/uploads, POST /sites/{id}/deployments and POST /sites/{id}/rollback. Retrying with the same key and body returns the original response (Idempotent-Replayed: true); the same key with a different body is refused. Keys last 24 hours.

Errors always look like this. code is from a fixed list; message is safe to show your user.

json
{ "code": "PLAN_TOO_SMALL",
  "message": "Cloud Solo has 512 MB of memory, which is not enough for a Next.js website. The smallest plan that fits is Cloud Solo 2 GB (cloud-solo-2gb).",
  "requestId": "req-1a2b",
  "details": { "minimumRamMb": 2048, "smallestFittingPlan": "cloud-solo-2gb" } }

Main codes: UNAUTHORIZED (401), SCOPE_MISSING (403), VALIDATION_FAILED (422, see details.fields), PLAN_NOT_AVAILABLE / PLAN_TOO_SMALL (422), DOMAIN_INVALID (422) / DOMAIN_IN_USE (409), ORDER_NOT_FOUND / SITE_NOT_FOUND (404, also when it is not yours), SITE_NOT_READY (409), DEPLOYMENT_IN_PROGRESS (409), BUILD_COMMAND_NOT_ALLOWED (422), RATE_LIMITED (429), INTERNAL_ERROR (500: retry with the same Idempotency-Key).

Key permissions: orders:read, orders:write, sites:read, uploads:write, deployments:read, deployments:write, webhooks:read, webhooks:write.

Check your key first: GET /me works with any valid key and returns your partner name and mode (sandbox or live), the key's permissions, your rate limit, the site types you can order, whether uploads are available (with the size limit and accepted archive types), and the webhook events you can receive.

Plans and site types

One plan is sold through the API: Cloud Solo, one website on its own server, in every server size. GET /plans lists them, smallest first, with price, memory, CPU, disk and the site types each one runs:

cloud-solo        512 MB   ₹1,450 / month
cloud-solo-1gb      1 GB   ₹1,699 / month
cloud-solo-2gb      2 GB   ₹2,799 / month
cloud-solo-4gb      4 GB   ₹5,499 / month
cloud-solo-8gb      8 GB   ₹9,999 / month
cloud-solo-16gb    16 GB   ₹18,999 / month
cloud-solo-32gb    32 GB   ₹36,999 / month

Prices include GST for customers in India; customers elsewhere are charged in their own currency without Indian GST, shown on the checkout page. Always read current prices from GET /plans.

Ask GHP Cloud which size to offer:

json
POST /plans/recommend
{ "siteType": "php", "monthlyVisitors": 20000, "buildSizeMb": 85 }

The answer is one size, the next size up, and a sentence you can show your user, for example: "Cloud Solo 1 GB: a PHP website with about 20,000 visits a month fits with room to grow." monthlyVisitors and buildSizeMb are optional. Ask at order time rather than storing the answer: the estimates are refined as real sites are measured.

Site types (siteType):

  • static: plain HTML, CSS and JavaScript. Upload the files, or a build with outputDir.
  • react: a static single-page build (falls back to /index.html), usually dist/ via outputDir.
  • php: PHP 8.1 to 8.4. composer install runs if composer.json exists and vendor/ does not.
  • laravel: needs at least 1 GB. GHP Cloud writes .env (database included), creates the app key, keeps storage/ between releases, and runs migrations if you ask.
  • nextjs: needs at least 2 GB. Upload a pre-built release (.next/ present); GHP Cloud installs its packages (npm ci) unless node_modules is included, and runs npm start.

Orders

json
POST /orders
{ "customer": { "email": "[email protected]", "name": "Asha Rao" },
  "planSlug": "cloud-solo-2gb", "billingCycle": "monthly",
  "siteType": "nextjs",
  "domain": "asharao-bakery.in",
  "partnerReference": "proj_123",
  "returnUrl": "https://app.builder.example/publish/done" }

planSlug defaults to cloud-solo and billingCycle to monthly. domain may be null: the temporary address is used until your user connects a domain. returnUrl must be https on a host GHP Cloud registered for you. The response (201) includes order.checkoutUrl.

  • Status AWAITING_APPROVAL instead of PENDING_CHECKOUT means the email already has a GHP Cloud login.
  • The checkout link is shown only in this response. POST /orders/{id}/checkout-link issues a new one (the old one stops working) with a fresh 72 hours.
  • Unpaid orders expire after 72 hours. A payment cannot be started in the last hour; once your user has started paying, the order gets 24 more hours and can no longer be cancelled by you.
  • GET /orders/{id}, GET /orders?status=, POST /orders/{id}/cancel (before payment only).

Order statuses: PENDING_CHECKOUT, AWAITING_APPROVAL, APPROVED, PAID, PROVISIONING, READY, PROVISION_FAILED (paid; GHP Cloud finishes the setup), CANCELLED, EXPIRED, DECLINED.

Sites and uploads

  • GET /sites, GET /sites/{id}: status, temporary address, SSL and DNS. Tell your user to point their domain's A record at dns.expectedA; SSL is issued automatically once it does (site.ssl_issued).
  • POST /sites/{id}/uploads with { "contentType": "application/gzip" | "application/zip", "sizeBytes": 1234567 } returns a signed upload form: upload.url and upload.fields. POST the archive there as multipart/form-data, with every entry of fields as form fields and the file last as file. The form is valid for 1 hour; the default limit is 500 MB.
  • POST /uploads/{id}/complete with { "sha256": "<hex of the file>", "sizeBytes": 1234567 }.
  • GET /uploads/{id} returns the upload's current status, size and expiry, if you need to check it again.

Archives are checked before they touch the website: no links or special files, no absolute paths or .., at most 200,000 files, unpacked size at most 4 times the archive. A single top-level folder is stripped automatically. Static and React uploads must not contain PHP files.

Deployments

json
POST /sites/{id}/deployments
{ "uploadId": "upl_...",
  "build": { "mode": "prebuilt", "installCommand": null, "buildCommand": null, "outputDir": "dist" },
  "laravel": { "migrate": false, "cacheConfig": true },
  "keepReleases": 2 }

Returns 202 with the deployment and its logsUrl. Steps: download, (Laravel: environment and storage), build, malware scan, switch, health check, keep the newest keepReleases.

Build commands are limited to npm ci / npm install, yarn install, pnpm install, composer install (with their usual flags), npm / yarn / pnpm run <script> and php artisan <command>. Builds run as the website's own user, inside its memory and CPU limits, for at most 30 minutes.

  • GET /deployments/{id}: status, summary (queued, building, live, failed, superseded, rolled_back), errorCode, errorMessage, logTail.
  • GET /deployments/{id}/logs: live log as Server-Sent Events (log, status, done; resumes from Last-Event-ID). ?follow=false returns it as text.
  • GET /sites/{id}/deployments, POST /sites/{id}/rollback (back to the previous release), GET /jobs/{jobId}.

Failure codes include ARCHIVE_REJECTED, ARCHIVE_CHECKSUM_MISMATCH, BUILD_FAILED, BUILD_MEMORY_UNAVAILABLE, SCAN_BLOCKED, HEALTH_CHECK_FAILED and SERVER_UNREACHABLE. In every case the previous release is still live.

Webhooks

GHP Cloud POSTs JSON to the address registered for you and retries for about two days (after 1, 5 and 15 minutes, then 1, 3, 6, 12 and 24 hours) until you answer with a 2xx.

X-GHP-Event: site.ready
X-GHP-Delivery-Id: <id>
X-GHP-Timestamp: 1767225600
X-GHP-Signature: sha256=<hex HMAC-SHA256 of "<timestamp>.<raw body>" with your webhook secret>

Verify before trusting (Node.js):

js
const ts = req.headers['x-ghp-timestamp']
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(ts + '.' + rawBody).digest('hex')
const ok = Math.abs(Date.now() / 1000 - Number(ts)) < 300 &&
  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-ghp-signature'] || ''))

Use the raw request body, not re-serialised JSON, and ignore a delivery id you have already handled.

Events: order.paid, order.cancelled, order.expired, order.declined, order.refunded, site.ready, site.failed, site.ssl_issued, site.deleted, site.access_revoked, deployment.started, deployment.succeeded, deployment.failed. Missed one? GET /webhook-deliveries?status=dead and POST /webhook-deliveries/{id}/redeliver.

Sandbox

Sandbox keys (ghpp_test_) skip payment: the checkout page still collects your user's details, then the order goes straight to paid and a real server is set up. A sandbox account can have up to 3 test sites at a time, and each is removed automatically 7 days after it was set up (you receive site.deleted).

Becoming a partner

Partner accounts, keys and webhook secrets are issued by GHP Cloud. Write to [email protected] with your product, your website and the address you want webhooks sent to. You start in the sandbox and move to live keys once your integration is ready.

Was this article helpful?

Need help? →