Offers

Get offer details

Retrieves the detailed configuration, pricing references, and metadata for a specific service Offer identified by its namespace and name.

Request overview

Feature	Details
Method	GET
Endpoint	https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/offer/{name}
Authentication	Bearer Token

Path parameters

• namespace (string): The unique identifier for the environment or tenant (e.g., 142034).
• name (string): The unique resource name of the offer (e.g., telr-test-001).

Headers

• Authorization (string): Required. Use the format Bearer <TOKEN>.

Response body schema

The response returns a JSON object representing the Offer resource.

1. Resource identifiers

• kind: The type of resource (offer).
• version: API version (e.g., v1alpha).
• metadata: Contains timestamps, labels, and geo-spatial data (lat/long coordinates and Plus Codes).

2. Specification (spec)

The spec block contains the core business logic and configuration for the offer:

Field	Description
**quoteRef / siteRef**	References to the parent Quote and associated Site objects.
terms	An array of contract durations (e.g., 36 months) and their validity status.
address	Full geographic details of the service location, including normalized street data and UK-specific fields (if applicable).
**gaa / litBldgs**	Pricing reference blocks for different connectivity types (DIA, Broadband, Ethernet).
networkConfiguration	Defines HA options and LAN interface types (e.g., copper).
templateSelection	Hardware/Software constraints such as firewall requirements, max bandwidth (e.g., 200 Mbps), and circuit limits.

3. Status and expiration

• state.phase: The current lifecycle stage of the offer (e.g., design).
• dateExpired: Epoch timestamp indicating when the offer pricing/validity expires.

Example response analysis

In the provided sample, the offer “telr-test-001” is for a site in Seattle, WA.

• Pricing: The offer has successful pricing hits (hasOfferings: true) for DIA and Ethernet via GAA, but no Broadband offerings under the “Lit Buildings” category.
• Hardware: It is configured for a maximum of 200 Mbps bandwidth and 2 WAN circuits.
• Lifecycle: The offer is currently in the design phase.

{
    "kind": "offer",
    "version": "v1alpha",
    "namespace": "142034",
    "name": "telr-test-001",
    "metadata": {
        "dateCreated": 1770659951657,
        "dateUpdated": 1770661506547,
        "annotations": [
            "net.gtt.offer/checksum/2e096aa3a1c836fadb745251d0665770c1a7c57d215e784a6c43ac657e62ea0f"
        ]
    },
    "spec": {
        "products": [
            {
                "productSpecification": {
                    "externalId": "access",
                    "productCategory": "connect"
                },
                "attributes": {
                    "type": "dia",
                    "speed": 100,
                    "ipSuffix": "/29"
                }
            }
        ],
        "templateSelection": {
            "highAvailability": 1,
            "firewall": 1,
            "platform": 1,
            "availableTemplates": [
                {
                    "id": "31",
                    "name": "EnvisionEDGE Virtual Router",
                    "platform": "EnvisionEDGE",
                    "max_bandwidth_mbps": 2750
                }
            ]
        },
        "state": {
            "phase": "design"
        }
    }
}

Partial update (PATCH) offer

This endpoint performs a partial update to an existing Offer resource using the JSON Patch (RFC 6902) standard. Unlike a PUT request, which requires sending the entire resource, PATCH allows you to modify specific fields—in this case, updating the product configuration without touching other metadata or site details.

1. Request overview

Component	Value
Method	PATCH
Endpoint	https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/offer/{name}
Content-Type	application/json
Authentication	Bearer Token

Path parameters

• namespace: The tenant ID (e.g., 142034).
• name: The specific offer ID (e.g., telr-test-001).

2. JSON patch operations

The request body uses a list of operation objects. This is a powerful way to ensure atomicity and precision when updating complex nested resources.

Update payload analysis

[
  {
    "op": "replace",
    "path": "/spec/products",
    "value": [ ... ]
  }
]

• op: The operation type (replace).
• path: The JSON pointer to the target field (/spec/products).
• value: The new array of product objects to be injected. In this example, it sets a DIA 100 Mbps service with a /29 IP suffix.

3. Response highlights

A successful PATCH returns the fully updated resource.

• Timestamps: The metadata.dateUpdated is refreshed to reflect the patch time (e.g., 1770918180746).
• Integrity: A new net.gtt.offer/checksum is generated in the annotations field. You must use this new checksum for any subsequent PUT or PATCH operations to avoid version conflicts.
• Side Effects: Updating the product configuration may trigger backend recalculations. Notice in the sample response that templateSelection.maxBandwidthMbps has been updated to 100 to align with the new product speed.

4. Comparison: PUT vs. PATCH

Feature	PUT	PATCH (JSON Patch)
Payload	Full resource object.	Array of specific operations.
Use Case	Overwriting a resource or full-state sync.	Precise updates to specific nested fields.
Risk	Can accidentally nullify fields if not sent.	High precision; only touches what is specified.

Sample request body

[
  {
    "op": "replace",
    "path": "/spec/products",
    "value": [
      {
        "productSpecification": {
          "externalId": "access",
          "productCategory": "connect"
        },
        "attributes": {
          "type": "dia",
          "speed": 100,
          "ipSuffix": "/29"
        }
      }
    ]
  }
]

Product specification documentation (JSON Patch)

This documentation covers the various configurations for the /spec/products array within the GTT Offer API. These payloads utilize the JSON Patch (RFC 6902) standard to replace existing product configurations with specific connectivity types, ranging from wireline Dedicated Internet Access (DIA) to wireless 5G solutions.

1. Wireline connectivity (DIA)

Used for standard Dedicated Internet Access over fiber or copper. These specifications require defined bandwidth speeds and IP allocation details.

Feature	DIA 100M Configuration	DIA 500M Configuration
externalId	access	access
Type	dia	dia
Speed	100 Mbps	500 Mbps
IP Subnet	/29	/29

Business Logic: Upgrading speed via PATCH allows for rapid re-quoting of a site without re-entering geographic or site-specific metadata.

2. Wireless connectivity (5G solutions)

Wireless products are categorized by their Role (Primary vs. Backup) and their Mounting Environment (Indoor vs. Outdoor). Unlike DIA, wireless specifications include an outdoor boolean to determine the necessary hardware and installation type.

A. 5G primary access

Designed for sites where 5G is the main circuit. It typically includes a speed attribute.

• Indoor Primary: Used for standard office environments where the 5G gateway is placed inside.
• outdoor: false, role: primary, speed: "100"
• Outdoor Primary: Used for sites requiring an external antenna or enclosure to ensure signal integrity.
• outdoor: true, role: primary, speed: "100"

B. 5G backup access

Designed for failover redundancy. These configurations typically omit the speed attribute as they rely on “Best Effort” wireless delivery during primary circuit outages.

• Indoor Backup: outdoor: false, role: backup
• Outdoor Backup: outdoor: true, role: backup

3. Attribute dictionary

The following table defines the key fields within the attributes object for all product types:

Attribute	Type	Description
type	String	The specific technology type (e.g., dia, 5G primary, 5G backup).
speed	String/Int	The provisioned bandwidth. (Note: Wireline uses Integer; Wireless often uses String).
ipSuffix	String	The CIDR notation for the IP handoff (e.g., /29 for 5 usable IPs).
outdoor	Boolean	true if outdoor hardware/mounting is required for signal optimization.
role	String	Defines the circuit hierarchy: primary or backup.

4. Implementation example (JSON patch)

To update an offer to an Outdoor 5G Primary configuration, use the following operation:

[
    {
        "op": "replace",
        "path": "/spec/products",
        "value": [
            {
                "productSpecification": {
                    "productCategory": "connect"
                },
                "attributes": {
                    "type": "5G primary",
                    "outdoor": true,
                    "speed": "100",
                    "role": "primary"
                }
            }
        ]
    }
]