Skip to content
GraviPointThe Centre of Productivity
  • AI AgentNew
  • Pricing
  • Community
Log inGet started free
TemplatesProject & Task ManagementAgile & ScrumAPI Documentation

DocumentAgile & ScrumFree

API Documentation

Reference docs developers can use straight away: authentication, endpoints, examples, errors, limits and webhooks.

Shown with sample data

Colour

[Parcelly] Shipping API: Reference

API version

[v1 (current)]

Production base URL

[https://api.parcelly.example/v1]

Sandbox base URL

[https://sandbox.api.parcelly.example/v1]

Format

[JSON over HTTPS; UTF-8]

Support

[developers@parcelly.example; status page: status.parcelly.example]

Last updated

[1 December 2026]

1. Overview

[The Parcelly API lets you get shipping rates, create shipments and labels, track parcels and receive status updates by webhook. All requests must use HTTPS. Timestamps are ISO 8601 in UTC; amounts are in minor units (cents) with an ISO 4217 currency code.]

2. Quick start

  1. [Create a sandbox account and copy your test API key from Dashboard > Developers.]

  2. [Call GET /rates with a test origin and destination to check your key works.]

  3. [Create a test shipment with POST /shipments and download the label from the label_url in the response.]

  4. [Register a webhook endpoint to receive tracking updates.]

  5. [When ready, switch to your live key and the production base URL.]

3. Authentication

[Authenticate with an API key sent as a bearer token in the Authorization header. Keys starting "sk_test_" work only in the sandbox; keys starting "sk_live_" work only in production. Keep keys secret and server-side; never embed them in mobile apps or browser code.]

Header

Value

Required

Authorization

[Bearer sk_live_51Hx...]

[Yes]

Content-Type

[application/json]

[For POST and PATCH]

Idempotency-Key

[A unique value per create request, e.g. a UUID]

[Recommended for POST]

Parcelly-Version

[2026-10-01]

[Optional: pins behaviour to a dated version]

4. Conventions

4.1 Versioning

[The major version is in the URL (/v1). Backward-compatible changes (new endpoints, new optional fields, new enum values) can be added at any time; build clients to ignore unknown fields. Breaking changes ship in a new major version with at least 12 months’ notice.]

4.2 Rate limits

[Each key may make 100 requests per second in production and 25 in the sandbox. Every response includes the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the limit returns 429; retry after the number of seconds in the Retry-After header.]

4.3 Pagination

[List endpoints use cursor pagination. Pass limit (1–100, default 25) and starting_after (the ID of the last item you received). The response includes has_more.]

4.4 Idempotency

[Send an Idempotency-Key header with every POST that creates a resource. Keys are kept for 24 hours; repeating a request with the same key returns the original response with the header Idempotent-Replayed: true.]

5. Endpoint summary

Method

Path

Description

GET

/rates

[Get available services and prices for a parcel]

POST

/shipments

[Create a shipment and purchase a label]

GET

/shipments/{shipment_id}

[Retrieve a shipment]

GET

/shipments

[List shipments, filtered by status or date]

POST

/shipments/{shipment_id}/cancel

[Cancel a shipment and refund the label]

GET

/tracking/{tracking_number}

[Get tracking events for a parcel]

POST

/webhook_endpoints

[Register a webhook endpoint]

6. Endpoint reference

6.1 Create a shipment

POST /shipments

[Creates a shipment, purchases a label for the chosen service and returns the label URL and tracking number.]

Body parameters

Field

Type

Required

Description

service

string

Yes

[Service code from GET /rates, e.g. "next_day"]

from_address

object

Yes

[Sender address: name, line1, line2, city, postal_code, country (ISO 3166-1 alpha-2), phone]

to_address

object

Yes

[Recipient address, same fields; email optional for delivery notifications]

parcel

object

Yes

[weight_grams (integer), length_cm, width_cm, height_cm]

reference

string

No

[Your order reference, max 50 characters; shown on the label]

label_format

string

No

["pdf" (default), "png" or "zpl"]

Example request

POST https://api.parcelly.example/v1/shipments with headers Authorization: Bearer sk_test_4eC39Hq, Idempotency-Key: 7f1c2d9e-0b4a-4f61-9a55-2c8e3b6d1f20

{"service": "next_day", "reference": "ORD-104822", "from_address": {"name": "Fernhill Outdoor Gear", "line1": "Unit 4, Riverside Park", "city": "Leeds", "postal_code": "LS10 1AB", "country": "GB"}, "to_address": {"name": "Sam Carter", "line1": "12 Elm Road", "city": "York", "postal_code": "YO10 3DD", "country": "GB", "email": "sam@example.com"}, "parcel": {"weight_grams": 1850, "length_cm": 40, "width_cm": 30, "height_cm": 12}}

Example response (201 Created)

{"id": "shp_9QwX2kLm", "status": "label_created", "service": "next_day", "tracking_number": "PC7730918842GB", "label_url": "https://files.parcelly.example/labels/shp_9QwX2kLm.pdf", "price": {"amount": 645, "currency": "GBP"}, "reference": "ORD-104822", "created_at": "2026-12-01T09:42:17Z"}

6.2 Retrieve a shipment

GET /shipments/{shipment_id}

Parameter

In

Type

Required

Description

shipment_id

path

string

Yes

[The shipment ID, e.g. shp_9QwX2kLm]

Example response (200 OK)

{"id": "shp_9QwX2kLm", "status": "in_transit", "tracking_number": "PC7730918842GB", "estimated_delivery": "2026-12-02", "last_event": {"code": "arrived_at_hub", "description": "Arrived at York delivery hub", "occurred_at": "2026-12-02T04:12:09Z"}}

Shipment status values: [label_created, picked_up, in_transit, out_for_delivery, delivered, exception, returned, cancelled.]

6.3 List shipments

GET /shipments

Parameter

In

Type

Required

Description

status

query

string

No

[Filter by status]

created_after

query

string

No

[ISO 8601 date-time]

limit

query

integer

No

[1–100, default 25]

starting_after

query

string

No

[Cursor: ID of the last shipment from the previous page]

Example response (200 OK)

{"object": "list", "has_more": true, "data": "(array of shipment objects as in 6.2)"}

6.4 Cancel a shipment

POST /shipments/{shipment_id}/cancel

[Cancels a shipment that has not been picked up and refunds the label price to your account balance within 24 hours. Returns 409 if the parcel has already been collected.]

Example response (200 OK)

{"id": "shp_9QwX2kLm", "status": "cancelled", "refund": {"amount": 645, "currency": "GBP", "status": "pending"}}

7. Errors

[Errors use standard HTTP status codes and a consistent JSON body with a machine-readable code, a human-readable message, the field at fault where relevant, and a request ID to quote to support.]

{"error": {"type": "invalid_request", "code": "postal_code_invalid", "message": "to_address.postal_code is not a valid postal code for country GB.", "field": "to_address.postal_code", "request_id": "req_3kT9aZ1"}}

Status

Type

Common codes

What to do

400

invalid_request

[missing_field, postal_code_invalid, parcel_too_heavy]

[Fix the request; do not retry unchanged]

401

authentication_error

[api_key_missing, api_key_invalid]

[Check the key and environment]

403

permission_error

[service_not_enabled]

[Ask your account manager to enable the service]

404

not_found

[shipment_not_found]

[Check the ID and environment]

409

conflict

[already_collected, idempotency_key_reused]

[Do not retry; check the resource state]

422

unprocessable

[address_undeliverable]

[Correct the address or choose another service]

429

rate_limited

[too_many_requests]

[Retry after the Retry-After seconds, with back-off]

500, 502, 503

api_error

[internal_error, carrier_unavailable]

[Retry with exponential back-off using the same Idempotency-Key]

8. Webhooks

[Register an HTTPS endpoint to receive events. Parcelly sends a POST with a JSON event body and expects a 2xx response within 10 seconds. Failed deliveries are retried with exponential back-off for up to 3 days. Events may arrive more than once or out of order: de-duplicate on the event ID and use occurred_at for ordering.]

Event type

Sent when

shipment.picked_up

[The carrier collects the parcel]

shipment.out_for_delivery

[The parcel is on the vehicle for delivery today]

shipment.delivered

[Delivery is confirmed]

shipment.exception

[A delivery problem occurs, e.g. address not found]

Example event

{"id": "evt_1Lm8Qa", "type": "shipment.delivered", "occurred_at": "2026-12-02T13:27:44Z", "data": {"shipment_id": "shp_9QwX2kLm", "tracking_number": "PC7730918842GB", "signed_by": "S. Carter"}}

Verifying signatures: [Each request includes a Parcelly-Signature header containing a timestamp and an HMAC-SHA256 signature of the timestamp and raw body, using your endpoint’s signing secret. Compute the signature and compare in constant time; reject requests older than 5 minutes.]

9. SDKs and tools

  • [Official libraries: Node.js, Python, PHP, Java]

  • [OpenAPI specification: https://api.parcelly.example/v1/openapi.json]

  • [Postman collection: [link]]

10. Changelog

Date

Change

Type

[2026-12-01]

[Added label_format "zpl" for thermal printers]

[Additive]

[2026-10-01]

[Added estimated_delivery to shipment objects]

[Additive]

[2026-07-15]

[Deprecated field "weight_kg"; use weight_grams. Removal on 2027-07-15]

[Deprecation]

Text in [brackets] is yours to replace.

  • About
  • What’s included
  • How to use
  • Questions
  • Related resources

About this template

Good API documentation gets a developer from API key to first successful call in minutes. This template covers the overview and base URLs, authentication, versioning, rate limits, pagination and idempotency, an endpoint summary table, a full reference for each endpoint with parameters and request and response examples, the error format and codes, webhooks with signature verification, and a changelog, worked through for a fictional shipping API.

Who it’s for

  • Public and partner REST APIs
  • Internal APIs used by other teams
  • Writing docs before building (API-first design)
  • Supplementing an OpenAPI specification with guidance

What’s included

  • 1. Overview
  • 2. Quick start
  • 3. Authentication
  • 4. Conventions
  • 5. Endpoint summary
  • 6. Endpoint reference
  • 7. Errors
  • 8. Webhooks
  • 9. SDKs and tools
  • 10. Changelog

How to use it

  1. 1Start with a quick start: how to get a key and make the first call.
  2. 2Document authentication, versioning, rate limits, pagination and errors once, in their own sections.
  3. 3For each endpoint, give the method and path, purpose, parameters with types and whether required, and a realistic request and response example.
  4. 4List every error code with what causes it and how to fix it.
  5. 5Keep a changelog and mark deprecated fields and endpoints with removal dates.

Tips

  • Use realistic example values (real-looking IDs, addresses, amounts). Developers copy examples, so they must work against the sandbox.
  • Generate the reference from your OpenAPI specification where you can, and write the guides (authentication, errors, webhooks) by hand.
  • Document what happens on failure and retry. Idempotency keys, timeouts and webhook retries cause most integration bugs.

Questions

What should API documentation include?

An overview, authentication, base URLs and environments, versioning, rate limits, pagination, an endpoint reference with parameters and examples, error codes, webhooks or events if used, SDKs, and a changelog.

What is an idempotency key?

A unique value the client sends with a request that creates something. If the request is retried with the same key, the API returns the original result instead of creating a duplicate, for example a second shipment.

Should API docs use OpenAPI (Swagger)?

An OpenAPI specification is the best source for the endpoint reference and lets you generate interactive docs and SDKs. You still need written guides for concepts, authentication and common workflows.

Related searchesapi documentation templaterest api documentationapi reference templateapi docs exampledeveloper documentationendpoint documentation

Details

Format
Document
Category
Agile & Scrum
Setup
120 min
Level
Advanced
Price
Free

Download a copy

Downloads need a free account.

DocumentAgile & ScrumFree

API Documentation

Reference docs developers can use straight away: authentication, endpoints, examples, errors, limits and webhooks.

A free account keeps your copy safe so you can come back to it. Have one? Log in

Download a copy

Downloads need a free account.

Details

Format
Document
Category
Agile & Scrum
Setup
120 min
Level
Advanced
Price
Free

Your copy is private to you.

More agile & scrum templates

View all
Sprint Backlog4 sheets

Committed

44

Done

15

Sprint progress

34%

ABCD
1StoryTypeEpicAssignee
2As a user I can reset my password by emailStoryAccountsAna
3Show order history with filtersStoryOrdersBen
4Checkout fails on expired cardBugPaymentsChen
5Upgrade logging libraryTech debtPlatformDee
Backlog
SpreadsheetAgile & Scrum

Sprint Backlog

User stories with points and status, a live burndown against the ideal line, and velocity from past sprints.

10 min setupPreview
Bug Tracker2 sheets

Open bugs

5

Open critical

1

SLA breached

4

ABCD
1TitleSeverityEnvironmentSteps to reproduce
2Checkout fails when card has expiredCriticalProductionAdd item, pay with expired test card
3Order history filter ignores date rangeMajorProductionFilter orders by last 30 days
4Typo on pricing pageTrivialProductionOpen /pricing
5Search is slow on large cataloguesMajorProductionSearch with 10,000+ products
Bugs
SpreadsheetAgile & Scrum

Bug Tracker

Bugs with severity, environment, owner and status, plus age, SLA breaches and time to resolve.

10 min setupPreview

Sprint Retrospective: Sprint 14

Date: Date · Facilitator: Name · Team: Team name

Sprint facts

Committed pointsCompleted pointsBugs found
31243

Last retro's actions

  • •Action: Done / Not done

What went well

  • •Item
  • •Item
DocumentAgile & Scrum

Sprint Retrospective

Run a focused retro: what went well, what to improve and owned actions.

15 min setupPreview

Practical guides and new resources, monthly.

One short email with new templates, calculators and how-tos. Unsubscribe any time.

GraviPointThe Centre of Productivity

Find the right resource. Make it work for you. Get things done with spreadsheets, documents, forms and calculators you can use right in your browser.

support@gravipoint.com
  • @gravipoint
  • @GraviPoint
  • GraviPoint
  • 𝕏@gravipoint

Templates

  • All templates
  • Budgets & expenses
  • Invoices & billing
  • Project management
  • HR & people
  • Inventory & stock
  • Sales & CRM
  • Financial calculators

Popular

  • Monthly budget
  • Invoice
  • Employee shift schedule
  • Weekly timesheet
  • Project plan & Gantt chart
  • Inventory tracker
  • Expense report
  • Mortgage calculator

Solutions

  • Individuals & households
  • Freelancers & consultants
  • Founders & startups
  • Small business owners
  • Teams & operations
  • Students & educators

Company

  • About
  • Features
  • Pricing
  • Community
  • Journal
  • Contact
© 2026 GraviPoint. All rights reserved.
  • Privacy
  • Terms
  • Help centre
  • FAQ