Models Reference¶

Every request and response shape has a typed Pydantic model. This page is a quick index of what each model represents and the fields you’ll use most often. For the full, auto-generated field lists, see the API Reference.

You can import any of these from the top-level package:

from pypresscart import Order, Campaign, CheckoutRequest, TokenInfo  # etc.

Models accept unknown fields silently — so if Presscart adds a new field, your existing code won’t break. See Forward compatibility at the bottom.

Shared primitives¶

`Paginated[T]`¶

Generic pagination envelope. Documented in Pagination.

class Paginated[T]:
    records: list[T]
    total_records: int | None
    total_pages: int | None
    current_page: int | None
    next_page: int | None
    previous_page: int | None

`Tag`¶

class Tag:
    name: str

`Price`¶

class Price:
    unit_amount: float      # see note below
    currency: str | None    # usually "usd"
    pricing_tier: str | None

Warning

Monetary units are not uniform across the Presscart API. On /products/listings, /products/{id}, and outlet channel prices, unit_amount is returned in cents (integer, e.g. 575 means $5.75). On /orders*, the money fields (total, subtotal, processing_fee, discount, etc.) come back in dollars (float, e.g. 154.5 means $154.50). pypresscart surfaces whatever the API returns — always confirm the unit for the endpoint you’re on before formatting.

`IncludeItem`¶

class IncludeItem:
    channel_type: ChannelType | str | None
    placement_type: PlacementType | str | None

Both types are nullable because the API occasionally returns null for them.

Enums¶

class ChannelType(str, Enum):
    WEBSITE, NEWSLETTER, INSTAGRAM, LINKEDIN,
    YOUTUBE, TIKTOK, TWITTER_X, PODCAST, OTHER

class PlacementType(str, Enum):
    FULL_FEATURE, PRESS_RELEASE, MENTION, QUOTE, LISTICLE

class OutletStatus(str, Enum):
    ACTIVE, INACTIVE, DRAFT, PENDING_REVIEW,
    PENDING_AGREEMENT, REJECTED, ARCHIVED, SUSPENDED

class TokenType(str, Enum):
    FULL_ACCESS = "full_access"
    CUSTOM = "custom"
    READ_ONLY = "read_only"

class SortOrder(str, Enum):
    ASC = "asc"
    DESC = "desc"

All enums accept either the enum value or a raw string — models declare the type as Enum | str for forward compatibility.

Auth¶

`TokenInfo`¶

Response from Auth.whoami().

Field	Type
`source`	`str`
`team_id`	`str`
`token_type`	`TokenType \| str`
`scopes`	`list[str]`
`pro_pricing_enabled`	`bool \| None`

Outlets¶

`Outlet`¶

Full outlet with outlet_channels, tags, metadata. Returned by client.outlets.get().

`OutletListing`¶

A row in client.outlets.list() / client.outlets.list_products(). id is a product id; outlet_id is the outlet.

`OutletChannel`, `OutletChannelSummary`¶

The detailed and summary forms of a channel on an outlet.

`CountriesResponse`, `StatesResponse`, `CitiesResponse`¶

Wrappers around {"countries": [...]} / {"states": [...]} / {"cities": [...]}.

`DisclaimerRecord`¶

class DisclaimerRecord:
    id: str
    name: str | None
    description: str | None

Products¶

`Product`¶

Full product (from client.products.get()).

`ProductListing`¶

Row in client.products.list_listings().

`ProductCategoryCount`¶

class ProductCategoryCount:
    type: str    # e.g. "FULL_FEATURE"
    count: int

Orders¶

`Order`¶

Full order; includes nested line_items, team, and payment metadata. See Orders.

`LineItem`¶

A single line on an order.

`CheckoutRequest`¶

Body for client.orders.create_checkout().

Field	Type
`profile_id`	`str`
`line_items`	`list[CheckoutLineItem]`
`discount`	`float \| None` (default `0`)
`apply_credits`	`bool \| None` (default `None` — omitted, so the API applies Team Credits; pass `False` to skip)

`CheckoutLineItem`¶

Field	Type
`product_id`	`str`
`quantity`	`int` (default `1`)
`is_add_on`	`bool` (default `False`)
`linked_order_line_item_id`	`str \| None`

`OutletRef`, `TeamRef`¶

Minimal embedded references inside Order.

Order Items¶

`OrderItem`¶

Team-wide order item (GET /order-items). Fields cover commissions, accounting, refunds, publisher payouts, and nested article/outlet/client references.

`ProfileOrderItem`¶

Slimmer shape returned by client.profiles.list_order_items() (bare-array endpoint).

Profiles¶

`Profile`¶

Brand/entity the team promotes.

Field	Type	Notes
`id`, `name`	`str`
`type`	`str`	e.g. `"COMPANY"`, `"INDIVIDUAL"`
`primary_goals`	`list[str]`	e.g. `["BRAND_AWARENESS"]`
`website_url`, `logo`, `location`	`str \| None`
(many more)		see source

Campaigns¶

`Campaign`¶

Full campaign, including optional nested profile, questionnaire, articles.

`CampaignCreateRequest`¶

See Campaigns — all fields required at the schema level, though many may be None.

`CampaignUpdateRequest`¶

All fields optional.

`Questionnaire`¶

Linked brief/research attached to a campaign.

`AssignOrderItemsRequest`¶

class AssignOrderItemsRequest:
    order_item_ids: list[str]

`QuestionnaireLinkRequest`¶

Field	Type
`file_id`	`str`
`file_url`	`str`
`file_name`	`str`
`file_size`	`int`

`ArticleStatus`, `ArticleStatusCount`¶

Status change entries / aggregate counts.

Articles¶

`Article`¶

Full article (from client.articles.get()).

`CampaignArticleRow`¶

Row in client.campaigns.list_articles().

`ArticleUpdateRequest`¶

Field	Type
`name`	`str \| None`
`brief_google_doc_url`	`str \| None`

`ApproveDraftRequest`¶

class ApproveDraftRequest:
    draft_google_doc_url: str | None

`ArticleWriter`, `ArticleOrderItem`, `ArticleStatusRef`¶

Embedded references.

`Comment`¶

A comment on an article, returned by client.articles.list_comments(), create_comment(), and update_comment(). Root comments carry up to one level of replies.

class Comment:
    id: str
    content: str | None
    author: CommentAuthor | None
    created_at: datetime | None
    updated_at: datetime | None
    parent_comment_id: str | None
    replies: list[Comment]    # one level deep; empty on reply objects

`CommentList`¶

Response from client.articles.list_comments() — records only, no pagination envelope.

class CommentList:
    records: list[Comment]

`CommentCreateRequest`¶

Body for client.articles.create_comment().

class CommentCreateRequest:
    content: str                     # 1–10,000 chars
    author: CommentAuthorInput
    parent_comment_id: str | None    # omit for root comments

`CommentAuthorInput`¶

Author block accepted by create_comment().

class CommentAuthorInput:
    name: str                        # 1–200 chars
    email: str | None
    external_id: str | None          # your id for the author; stored for audit

`CommentUpdateRequest`¶

class CommentUpdateRequest:
    content: str    # 1–10,000 chars

`CommentAuthor`¶

Author block on a comment response.

class CommentAuthor:
    name: str | None
    email: str | None

`CommentArchiveResponse`¶

Empty marker returned by client.articles.archive_comment(). The archive endpoint responds 204 No Content, so this model has no fields ({} in JSON mode).

Files¶

`File`¶

A file record with file_key, file_url, size, mime_type, folder_id, timestamps.

`UploadedFile`, `UploadFilesResponse`¶

Shape returned by client.files.upload():

class UploadFilesResponse:
    files: list[UploadedFile]

`MoveFilesRequest`¶

class MoveFilesRequest:
    file_ids: list[str]
    folder_id: str | None

`MoveFilesResponse`¶

class MoveFilesResponse:
    moved_count: int

`DeleteFileResponse`¶

class DeleteFileResponse:
    success: bool

Folders¶

`Folder`¶

class Folder:
    id: str
    name: str | None
    team_id: str | None
    created_by: str | None
    created_at: datetime | None
    updated_at: datetime | None
    deleted_at: datetime | None

`FolderCreateRequest`, `FolderRenameRequest`¶

class FolderCreateRequest:
    name: str

class FolderRenameRequest:
    name: str

`DeleteFolderResponse`¶

class DeleteFolderResponse:
    success: bool

Working with models¶

Construct¶

from pypresscart import CheckoutRequest, CheckoutLineItem

body = CheckoutRequest(
    profile_id="prof_1",
    line_items=[CheckoutLineItem(product_id="prod_1")],
)

Validate from a dict¶

from pypresscart import Order

order = Order.model_validate(raw_dict)

Dump to JSON-compatible dict¶

body.model_dump(mode="json", exclude_none=True)

This is how pypresscart serializes request bodies internally. exclude_none=True keeps payloads lean by dropping None-valued fields, which is correct for the vast majority of endpoints (an omitted key behaves the same as null). A few endpoints — notably POST /campaigns — require a key to be present even when its value is null; for those the library serializes with exclude_none=False. You don’t need to think about this when calling resource methods, but it matters if you’re dumping a model by hand to send it yourself.

Forward compatibility¶

If Presscart adds a new field to a response, pypresscart won’t raise a validation error — the extra data is preserved on the parsed model (accessible as model.model_extra) but not typed. Upgrade the library to pick up the typed attribute once it’s available.

Lenient parsing¶

The API occasionally sends an empty string ("") in place of null for optional fields — especially booleans and dates. pypresscart normalizes "" to None before validation, so you don’t get spurious type errors on what is semantically a missing value.

If you need the raw payload byte-for-byte, use as_json=True (see Dual-Mode I/O).

Models Reference¶

Shared primitives¶

Paginated[T]¶

Tag¶

Price¶

IncludeItem¶

Enums¶

Auth¶

TokenInfo¶

Outlets¶

Outlet¶

OutletListing¶

OutletChannel, OutletChannelSummary¶

CountriesResponse, StatesResponse, CitiesResponse¶

DisclaimerRecord¶

Products¶

Product¶

ProductListing¶

ProductCategoryCount¶

Orders¶

Order¶

LineItem¶

CheckoutRequest¶

CheckoutLineItem¶

OutletRef, TeamRef¶

Order Items¶

OrderItem¶

ProfileOrderItem¶

Profiles¶

Profile¶

Campaigns¶

Campaign¶

CampaignCreateRequest¶

CampaignUpdateRequest¶

Questionnaire¶

AssignOrderItemsRequest¶

QuestionnaireLinkRequest¶

ArticleStatus, ArticleStatusCount¶