POS Integration Guide (IMPORTANT)

This API is designed for fulfilling shop POS systems to receive and manage incoming GetBloomDirect orders.

Supported v1 Workflow

PENDING_ACCEPTANCE → ACCEPTED_AWAITING_PAYMENT → PAID_AWAITING_FULFILLMENT → COMPLETED

What v1 POS integrations should support:

  • Retrieve incoming orders assigned to the fulfilling shop
  • Accept or decline pending orders
  • Require a decline reason when declining an order
  • Mark eligible orders as completed after fulfillment

Not included in v1

  • Creating outbound orders from the POS
  • Marking orders paid from the POS
  • Settlement calculations inside the POS

Money Format

GetBloomDirect stores monetary values internally in cents, but the POS API returns dollar amounts as JSON numbers in USD.

Example: 50 means $50.00, and 59.99 means $59.99.

Decline Reasons

  • OUT_OF_STOCK
  • TOO_BUSY
  • DELIVERY_TOO_FAR
  • OTHER

If declineReason = "OTHER", then declineMessage is required.

Example:

{
  "declineReason": "OTHER",
  "declineMessage": "We are closing early today"
}

Authentication

All external v1 API requests must include your shop's API key.

x-api-key: YOUR_API_KEY

You can generate and manage your API key from your GetBloomDirect dashboard under POS API Access.

Only Pro shops can use the external POS API. If your subscription becomes inactive, API access will stop until Pro access is restored.

Orders API

GET/v1/orders

Retrieve incoming orders assigned to your fulfilling shop.

Headers

{
  "x-api-key": "YOUR_API_KEY"
}

Example Request

curl -X GET https://api.getbloomdirect.com/v1/orders \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ord_123",
        "orderNumber": "1001",
        "status": "PENDING_ACCEPTANCE",
        "recipient": {
          "fullName": "Jane Doe",
          "address": "123 Main St",
          "apt": "Apt 4B",
          "city": "Buffalo",
          "state": "NY",
          "zip": "14201",
          "phone": "555-123-4567",
          "email": "jane@example.com",
          "company": "Acme Corp",
          "message": "Happy Birthday!"
        },
        "customer": {
          "fullName": "John Smith",
          "email": "john@example.com",
          "phone": "555-987-6543"
        },
        "products": [
          {
            "id": "prod_1",
            "name": "Red Roses",
            "description": "Dozen premium roses",
            "photo": "https://cdn.getbloomdirect.com/products/roses.jpg",
            "qty": 1,
            "taxable": true,
            "price": 59.99
          }
        ],
        "totals": {
          "currency": "USD",
          "productsSubtotal": 59.99,
          "deliveryFee": 10,
          "tax": 4.8,
          "total": 74.79
        },
        "delivery": {
          "date": "2026-04-20T00:00:00.000Z",
          "window": {
            "type": "window",
            "from": "09:00",
            "to": "13:00"
          },
          "instructions": "Leave at front desk"
        },
        "timestamps": {
          "created": "2026-04-15T12:00:00.000Z",
          "accepted": null,
          "declined": null,
          "completed": null,
          "updated": "2026-04-15T12:00:00.000Z"
        }
      }
    ]
  },
  "meta": {
    "timestamp": "2026-04-16T12:00:00.000Z",
    "version": "1.0"
  }
}

Possible Errors

  • MISSING_API_KEY: Your API key is missing!
  • INVALID_API_KEY: You are trying to use an invalid API key
  • PRO_REQUIRED: This feature requires an active Pro subscription
  • ACCOUNT_SUSPENDED: Account suspended
POST/v1/orders/:id/accept

Accept an incoming order.

Headers

{
  "x-api-key": "YOUR_API_KEY"
}

Example Request

curl -X POST https://api.getbloomdirect.com/v1/orders/ord_123/accept \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "order": {
      "id": "ord_123",
      "orderNumber": "1001",
      "status": "ACCEPTED_AWAITING_PAYMENT",
      "recipient": {
        "fullName": "Jane Doe",
        "address": "123 Main St",
        "apt": "Apt 4B",
        "city": "Buffalo",
        "state": "NY",
        "zip": "14201",
        "phone": "555-123-4567",
        "email": "jane@example.com",
        "company": "Acme Corp",
        "message": "Happy Birthday!"
      },
      "customer": {
        "fullName": "John Smith",
        "email": "john@example.com",
        "phone": "555-987-6543"
      },
      "products": [
        {
          "id": "prod_1",
          "name": "Red Roses",
          "description": "Dozen premium roses",
          "photo": "https://cdn.getbloomdirect.com/products/roses.jpg",
          "qty": 1,
          "taxable": true,
          "price": 59.99
        }
      ],
      "totals": {
        "currency": "USD",
        "productsSubtotal": 59.99,
        "deliveryFee": 10,
        "tax": 4.8,
        "total": 74.79
      },
      "delivery": {
        "date": "2026-04-20T00:00:00.000Z",
        "window": {
          "type": "window",
          "from": "09:00",
          "to": "13:00"
        },
        "instructions": "Leave at front desk"
      },
      "timestamps": {
        "created": "2026-04-15T12:00:00.000Z",
        "accepted": "2026-04-15T14:12:00.000Z",
        "declined": null,
        "completed": null,
        "updated": "2026-04-15T14:12:00.000Z"
      }
    }
  },
  "meta": {
    "timestamp": "2026-04-16T12:00:00.000Z",
    "version": "1.0"
  }
}

Possible Errors

  • MISSING_API_KEY: Your API key is missing!
  • INVALID_API_KEY: You are trying to use an invalid API key
  • ACCOUNT_SUSPENDED: Account suspended
  • ORDER_NOT_FOUND: Order not found
  • UNAUTHORIZED: Not authorized
  • READ_ONLY_MODE: Upgrade to Pro to modify orders
  • INVALID_REQUEST: Something went wrong
POST/v1/orders/:id/decline

Decline an incoming order. Requires declineReason. declineMessage is required only when declineReason is OTHER.

Headers

{
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body

{
  "declineReason": "OTHER",
  "declineMessage": "We are closing early today"
}

Example Request

curl -X POST https://api.getbloomdirect.com/v1/orders/ord_123/decline \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "declineReason": "OTHER",
    "declineMessage": "We are closing early today"
  }'

Example Response

{
  "success": true,
  "data": {
    "order": {
      "id": "ord_123",
      "orderNumber": "1001",
      "status": "DECLINED",
      "recipient": {
        "fullName": "Jane Doe",
        "address": "123 Main St",
        "apt": "Apt 4B",
        "city": "Buffalo",
        "state": "NY",
        "zip": "14201",
        "phone": "555-123-4567",
        "email": "jane@example.com",
        "company": "Acme Corp",
        "message": "Happy Birthday!"
      },
      "customer": {
        "fullName": "John Smith",
        "email": "john@example.com",
        "phone": "555-987-6543"
      },
      "products": [
        {
          "id": "prod_1",
          "name": "Red Roses",
          "description": "Dozen premium roses",
          "photo": "https://cdn.getbloomdirect.com/products/roses.jpg",
          "qty": 1,
          "taxable": true,
          "price": 59.99
        }
      ],
      "totals": {
        "currency": "USD",
        "productsSubtotal": 59.99,
        "deliveryFee": 10,
        "tax": 4.8,
        "total": 74.79
      },
      "delivery": {
        "date": "2026-04-20T00:00:00.000Z",
        "window": {
          "type": "window",
          "from": "09:00",
          "to": "13:00"
        },
        "instructions": "Leave at front desk"
      },
      "timestamps": {
        "created": "2026-04-15T12:00:00.000Z",
        "accepted": null,
        "declined": "2026-04-15T14:15:00.000Z",
        "completed": null,
        "updated": "2026-04-15T14:15:00.000Z"
      }
    }
  },
  "meta": {
    "timestamp": "2026-04-16T12:00:00.000Z",
    "version": "1.0"
  }
}

Possible Errors

  • MISSING_API_KEY: Your API key is missing!
  • INVALID_API_KEY: You are trying to use an invalid API key
  • ACCOUNT_SUSPENDED: Account suspended
  • ORDER_NOT_FOUND: Order not found
  • UNAUTHORIZED: Not authorized
  • READ_ONLY_MODE: Upgrade to Pro to modify orders
  • MISSING_DECLINE_REASON: Decline reason required
  • MISSING_DECLINE_MESSAGE: Message required
  • INVALID_REQUEST: Something went wrong
POST/v1/orders/:id/complete

Mark an eligible order as completed after fulfillment.

Headers

{
  "x-api-key": "YOUR_API_KEY"
}

Example Request

curl -X POST https://api.getbloomdirect.com/v1/orders/ord_123/complete \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "order": {
      "id": "ord_123",
      "orderNumber": "1001",
      "status": "COMPLETED",
      "recipient": {
        "fullName": "Jane Doe",
        "address": "123 Main St",
        "apt": "Apt 4B",
        "city": "Buffalo",
        "state": "NY",
        "zip": "14201",
        "phone": "555-123-4567",
        "email": "jane@example.com",
        "company": "Acme Corp",
        "message": "Happy Birthday!"
      },
      "customer": {
        "fullName": "John Smith",
        "email": "john@example.com",
        "phone": "555-987-6543"
      },
      "products": [
        {
          "id": "prod_1",
          "name": "Red Roses",
          "description": "Dozen premium roses",
          "photo": "https://cdn.getbloomdirect.com/products/roses.jpg",
          "qty": 1,
          "taxable": true,
          "price": 59.99
        }
      ],
      "totals": {
        "currency": "USD",
        "productsSubtotal": 59.99,
        "deliveryFee": 10,
        "tax": 4.8,
        "total": 74.79
      },
      "delivery": {
        "date": "2026-04-20T00:00:00.000Z",
        "window": {
          "type": "window",
          "from": "09:00",
          "to": "13:00"
        },
        "instructions": "Leave at front desk"
      },
      "timestamps": {
        "created": "2026-04-15T12:00:00.000Z",
        "accepted": "2026-04-15T14:12:00.000Z",
        "declined": null,
        "completed": "2026-04-15T15:00:00.000Z",
        "updated": "2026-04-15T15:00:00.000Z"
      }
    }
  },
  "meta": {
    "timestamp": "2026-04-16T12:00:00.000Z",
    "version": "1.0"
  }
}

Possible Errors

  • MISSING_API_KEY: Your API key is missing!
  • INVALID_API_KEY: You are trying to use an invalid API key
  • ACCOUNT_SUSPENDED: Account suspended
  • ORDER_NOT_FOUND: Order not found
  • UNAUTHORIZED: Not authorized
  • READ_ONLY_MODE: Upgrade to Pro to modify orders
  • INVALID_REQUEST: Something went wrong